> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks for Apps

> Receive signed webhooks for each installation of your app. Verify the signature, handle the 7 app event types and the privacy events, and read about retries and the events that an app gets.

## Set up the endpoints

An app has one endpoint for live installs (`webhook_url`) and one for test installs (`webhook_url_test`). Set them in the wizard, or on the **Configuration** tab of the app page. Test events go out only if you set `webhook_url_test`. Without it, the app page shows a warning. Both URLs must use `https`.

## Which events your app gets

An app gets a merchant event only if both of these are true:

1. The app subscribed to the event type.
2. The install granted the read scope of the resource of the event.

| Event family | Required scope |
| - | - |
| `payment.*` | `payments:read` |
| `refund.*` | `refunds:read` |
| `dispute.*` | `disputes:read` |
| `subscription.*` | `subscriptions:read` |
| `customer.*` | `customers:read` |
| `license_key.*` | `license_keys:read` |

The app always gets its own app events, with no scope check. The app also gets the privacy events (see below).

> [!WARNING]
>
> `payment.*` events need only `payments:read`. They carry the full payload, with the customer name and email. Handle this data under your privacy policy.

## Payload

Every webhook has these fields at the top level:

```json theme={null}
{
  "livemode": true,
  "business_id": "bus_xxx",
  "installation_id": "ains_xxx",
  "app_id": "app_xxx",
  "type": "payment.succeeded",
  "timestamp": "2026-11-16T10:30:00Z",
  "data": {}
}
```

| Field | Meaning |
| - | - |
| `livemode` | `true` for a live install, `false` for a test install |
| `business_id` | The business that installed the app |
| `installation_id` | The install that the event belongs to |
| `app_id` | Your app |
| `type` | The event type |
| `timestamp` | The time of the event |
| `data` | The event data. For merchant events it has the same shape as the merchant webhook for that event. |

## Verify the signature

Dodo Payments signs each message with the Standard Webhooks headers `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Verify them against the raw request body with the signing secret of the endpoint.

To get the secret, open your app under **Apps**, **Created**, and read the **Webhook signing secret** card. The card shows the secret of the current mode. Set the webhook URL for a mode before you read its secret. Only a member of the owner business with write access to API keys can see it.

![The Webhook signing secret card with the endpoint, the masked secret, and the Rotate secret button](https://mintcdn.com/dodopayments/clOL2gp3BmPo5w6L/images/app-marketplace/developer/10-webhook-signing-secret-card.png?fit=max\&auto=format\&n=clOL2gp3BmPo5w6L\&q=85\&s=a6dd92583848cbf966577b2b1eb7c524)

```typescript TypeScript theme={null}
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.DODO_APP_WEBHOOK_SECRET!); // whsec_xxx

export function handle(rawBody: string, headers: Record<string, string>) {
  const event = wh.verify(rawBody, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
  }) as { type: string; installation_id: string; data: unknown };

  switch (event.type) {
    case "app.installed":
      // Save the installation.
      break;
    case "app.uninstalled":
      // Stop work for this installation.
      break;
  }
}
```

For more languages, see [Webhooks](https://docs.dodopayments.com/developer-resources/webhooks.md).

To replace the secret, select **Rotate secret**. The old secret stays valid for 24 hours, so update your server in that time.

## Respond and retry

Return a `2xx` response quickly. Use `webhook-id` to ignore a message that you already processed. If your endpoint does not return `2xx`, Dodo Payments sends the message again. See [Webhooks](https://docs.dodopayments.com/developer-resources/webhooks.md) for the retry schedule.

## App event types

An app gets these events for its own installs. `data` has `payload_type` set to `AppInstallation`, except for `app.settings.updated`.

| Event | When |
| - | - |
| `app.installed` | A merchant installed the app and the install is active. |
| `app.installation.updated` | The scopes of the install changed. |
| `app.uninstalled` | The install ended: the merchant uninstalled, the grant was revoked, or the app was deleted. |
| `app.settings.updated` | The merchant saved the settings. See [Settings webhook](https://docs.dodopayments.com/developer-resources/apps/app-settings/settings-webhook.md). |

### Example: app.installed

```json theme={null}
{
  "livemode": false,
  "business_id": "bus_xxx",
  "installation_id": "ains_xxx",
  "app_id": "app_xxx",
  "type": "app.installed",
  "timestamp": "2026-11-16T10:30:00Z",
  "data": {
    "payload_type": "AppInstallation",
    "installation_id": "ains_xxx",
    "app_id": "app_xxx",
    "business_id": "bus_xxx",
    "status": "active",
    "granted_scopes": ["payments:read", "customers:read"],
    "livemode": false,
    "created_at": "2026-11-16T10:29:50Z",
    "updated_at": "2026-11-16T10:30:00Z",
    "uninstalled_at": null
  }
}
```

`app.installation.updated` and `app.uninstalled` have the same shape. On `app.uninstalled`, `status` is `uninstalled` and `uninstalled_at` has a value.

## Privacy webhooks

The three privacy events are `customer.data_request`, `customer.redact`, and `business.redact`.

| Event | When | What your app must do |
| - | - | - |
| `customer.data_request` | A customer asks for their data. | Send the data that your app holds about the customer, to the merchant, as your privacy policy says. |
| `customer.redact` | A customer asks to delete their data. | Delete or make anonymous the data about the customer. |
| `business.redact` | 48 hours after the uninstall. | Delete or make anonymous all data about the business. |

* A public app that has `customers` scopes must handle all three events before it can be listed.
* Return a `2xx` response when you receive an event. Finish the request within 30 days.
* `business.redact` is not sent if the business installs the app again in the same mode within the 48 hours.
* `business.redact` and `app.uninstalled` go to your last `webhook_url`, also when the app is suspended or deleted.

## Test the webhooks

Install your own app in test mode with `webhook_url_test` set. You get `app.installed` when the install is active. Uninstall it to get `app.uninstalled`. See [Test your app](https://docs.dodopayments.com/developer-resources/apps/test-your-app.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.