Skip to content
Ideasoft
App Store

Uninstall (Uninstall Hook)

When a merchant uninstalls your app from the App Store, the App Store sends a notification to your Uninstall Hook URL. You are expected to delete the store's records when you receive it.

  1. 1.Merchant→App Store

    Uninstalls the app

  2. 2.App Store→Your uninstall hook

    Sends the uninstall notification

    POST with username, hash and domain in the JSON body.

  3. 3.Your uninstall hook

    Verifies the hash and deletes the store's data

  4. 4.Your uninstall hook→App Store

    Returns HTTP 200

    For any other response the notification is retried a limited number of times.

Request

Code
POST https://your-app.example.com/ideasoft/uninstall Content-Type: application/json { "username": "b277c22af6e6dad43c3ac70c65a85ddd", "hash": "e86628c8bc958d88d62af73974554f0de3f30674012c85f2cf8cd905214a5631", "domain": "https://your-store.myideasoft.com" }
FieldDescription
usernameMD5 digest of the store address: md5("https://your-store.myideasoft.com").
hashHMAC-SHA256 signature (hex) of the text {"username":"<username>"}, keyed with your Client Secret.
domainThe address of the store that uninstalled the app, including the scheme.

Verification

  1. Recompute hash from the username in the body and compare in constant time. The signed text is PHP json_encode output: {"username":"b277c22af6e6dad43c3ac70c65a85ddd"}.
  2. Check that username equals md5(domain).
  3. If verification succeeds, delete the store's tokens and records, then return HTTP 200.
<?php $body = json_decode(file_get_contents('php://input'), true) ?: []; $username = (string)($body['username'] ?? ''); $domain = (string)($body['domain'] ?? ''); $secret = getenv('IDEASOFT_CLIENT_SECRET'); $expected = hash_hmac('sha256', json_encode(['username' => $username]), $secret); $validHash = hash_equals($expected, (string)($body['hash'] ?? '')); $validUser = hash_equals(md5($domain), $username); if (!$validHash || !$validUser) { http_response_code(401); exit; } // Delete the store's tokens and records (return 200 even if already deleted) http_response_code(200);

Test vector: for client_secret=example-client-secret and domain=https://your-store.myideasoft.com, username is b277c22af6e6dad43c3ac70c65a85ddd and hash is e86628c8bc958d88d62af73974554f0de3f30674012c85f2cf8cd905214a5631. The request above uses these values; you can try your endpoint with curl:

TerminalCode
curl -X POST https://your-app.example.com/ideasoft/uninstall \ -H 'Content-Type: application/json' \ -d '{"username":"b277c22af6e6dad43c3ac70c65a85ddd","hash":"e86628c8bc958d88d62af73974554f0de3f30674012c85f2cf8cd905214a5631","domain":"https://your-store.myideasoft.com"}'

Response and retries

  • Only HTTP 200 counts as success. Any other response, including 201 and 204, and connection errors count as failures.
  • A failed notification is retried a limited number of times through a queue; the delay between attempts is not guaranteed.
  • The same store may be notified more than once. Make your handler idempotent: return 200 even if the records are already deleted.
  • Respond quickly; run long deletions in the background.

Earlier format

Earlier versions sent username and hash in the Uninstall Hook URL's path or query string. In the current format all fields are in the JSON request body, and the domain field was added.

If the store installs the app again, the installation flow runs from the start.

Last modified on