# 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.

<Steps>
  <Step from="merchant" to="appstore" title="Uninstalls the app" />
  <Step from="appstore" to="hook" title="Sends the uninstall notification">
    `POST` with `username`, `hash` and `domain` in the JSON body.
  </Step>
  <Step from="hook" title="Verifies the hash and deletes the store's data" />
  <Step from="hook" to="appstore" title="Returns HTTP 200">
    For any other response the notification is retried a limited number of times.
  </Step>
</Steps>

## Request

```http
POST https://your-app.example.com/ideasoft/uninstall
Content-Type: application/json

{
  "username": "b277c22af6e6dad43c3ac70c65a85ddd",
  "hash": "e86628c8bc958d88d62af73974554f0de3f30674012c85f2cf8cd905214a5631",
  "domain": "https://your-store.myideasoft.com"
}
```

| Field | Description |
|---|---|
| `username` | MD5 digest of the store address: `md5("https://your-store.myideasoft.com")`. |
| `hash` | HMAC-SHA256 signature (hex) of the text `{"username":"<username>"}`, keyed with your Client Secret. |
| `domain` | The 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**.

<CodeTabs>

```php title="PHP"
<?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);
```

```js title="Node.js"
import crypto from "node:crypto";

// ideasoftHmac and safeEqual helpers: same as in the Installation and Authorization example
export function verifyUninstall(body, clientSecret) {
  const username = String(body.username ?? "");
  const expected = ideasoftHmac({ username }, clientSecret);
  const md5 = crypto.createHash("md5").update(String(body.domain ?? "")).digest("hex");
  return safeEqual(expected, body.hash ?? "") && safeEqual(md5, username);
}
```

```python title="Python"
# ideasoft_hmac helper: same as in the Installation and Authorization example
def verify_uninstall(body, client_secret):
    username = str(body.get("username", ""))
    expected = ideasoft_hmac({"username": username}, client_secret)
    md5 = hashlib.md5(str(body.get("domain", "")).encode()).hexdigest()
    valid_hash = hmac.compare_digest(expected, str(body.get("hash", "")))
    return valid_hash and hmac.compare_digest(md5, username)
```

</CodeTabs>

**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`:

```bash
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.

:::note{title="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](/app-store/installation) runs from the start.
