Skip to main content

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.
The app always gets its own app events, with no scope check. The app also gets the privacy events (see below).
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:

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.
TypeScript
For more languages, see Webhooks. 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 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.

Example: app.installed

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.
  • 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.
Last modified on November 16, 2026