Webhooks - AppDNA

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your AppDNA application. When a subscribed event fires, AppDNA sends a POST request to your configured endpoint with a JSON payload describing the event.

Supported Event Types

AppDNA supports 16 webhook event types:

Event Type	Trigger
`onboarding.started`	User begins an onboarding flow
`onboarding.completed`	User completes an onboarding flow
`survey.completed`	User submits a survey response
`payment.completed`	Sent when the store’s own server notification of a paid charge reaches AppDNA, so App Store Server Notifications V2 (iOS) or Google Play Real-Time Developer Notifications (Android) must be connected. It is never sent from your app’s purchase report. It covers a purchase, a resubscribe, a renewal (including a recovery from billing retry), a paid offer that starts, restarts or immediately upgrades a subscription, a trial converting to paid, an immediate App Store upgrade, and a Google Play subscription recovering from account hold. It is not sent for a free-trial start (an App Store free-trial offer, or a Google Play charge in its free-trial phase), an App Store transaction whose reported price is 0 (a Google Play charge is not checked for a price of 0), a Family Sharing member’s access, a change that takes effect at the next renewal (a scheduled App Store downgrade, or an offer redeemed on an active subscription; the renewal that charges it sends the webhook), a Google Play subscription restarted before its paid period ended, a Google Play charge notification processed while the subscription is revoked or refunded in AppDNA, or a one-time (non-subscription) purchase. On the App Store there is one webhook per `transactionId`, in whatever order the notifications arrive: the first notification that reports the transaction as a payment sends it, even when it arrives after a later transaction, and a repeated notification sends nothing. On Google Play there is one per charge notification (Play sends one per charge), sent while Play reports the subscription active, or canceled with its paid period still running; a redelivered notification sends nothing. Google Play has three exceptions: a charge notification processed after Play has moved the subscription to grace period, account hold, paused or expired sends nothing; two charge notifications processed after the later renewal send two webhooks with the same `transaction_id` (the later order’s id); and a free-trial purchase notification processed after the trial has converted to paid is judged by the phase Play reports at that time, so it sends a webhook too, and the trial start and the conversion send two webhooks with the conversion’s `transaction_id`. See Payment completed data for the price, currency and transaction id. AppDNA sends no store-driven webhook (`payment.completed`, `payment.failed`, `subscription.canceled`) for a notification about a subscription it has no record of, except a new purchase: an App Store `SUBSCRIBED`, or `OFFER_REDEEMED` for an initial buy or resubscribe; a Google Play `SUBSCRIPTION_PURCHASED` that Play confirms as active or canceled.
`payment.failed`	Sent when the store’s own server notification reports a failed renewal or a revocation, so App Store Server Notifications V2 (iOS) or Google Play Real-Time Developer Notifications (Android) must be connected. `data.error` is `billing_retry_started` for an App Store renewal that failed (`DID_FAIL_TO_RENEW`, also when a grace period starts), and `revoked` for an App Store `REVOKE` (for example, Family Sharing access withdrawn) or a Google Play `SUBSCRIPTION_REVOKED` that Play confirms (the subscription is expired). It is not sent for a failed first purchase, a Google Play subscription entering grace period or account hold, an App Store refund (`REFUND`), or an App Store notification about a transaction older than the one the subscription already carries (for example, a renewal failure processed after its recovery). `data` carries `user_id`, `product_id`, `environment`, `error` and `platform`.
`subscription.canceled`	Sent when the store reports that the user turned off auto-renew: an App Store `DID_CHANGE_RENEWAL_STATUS` with subtype `AUTO_RENEW_DISABLED`, or a Google Play `SUBSCRIPTION_CANCELED` that Play’s state confirms (canceled, expired, or active with auto-renew off). The subscription usually stays active until its paid period ends. Turning auto-renew back on (App Store `AUTO_RENEW_ENABLED`, Google Play `SUBSCRIPTION_RESTARTED`) sends no webhook. An App Store auto-renew change signed before a later auto-renew change or charge that AppDNA already recorded sends nothing (Apple can deliver them out of order). `data` carries `user_id`, `product_id`, `environment`, `cancel_reason` (`voluntary` for an App Store auto-renew-off, and when Play reports auto-renew off; otherwise the reason AppDNA recorded earlier, or `canceled`) and `effective_date` (App Store: when Apple signed the auto-renew-off notification; Google Play: when AppDNA first recorded auto-renew as off, not the end of the paid period, or the time AppDNA processed the notification when neither Play nor AppDNA has a cancellation date).
`push.delivered`	Push notification delivered to device
`push.opened`	User taps a push notification
`email.opened`	User opens an email
`email.clicked`	User clicks a link in an email
`message.clicked`	User interacts with an in-app message
`journey.completed`	User completes a journey/lifecycle flow
`journey.exited`	User exits a journey before completion
`experiment.exposure`	User is exposed to an experiment variant
`user.identified`	Anonymous user is linked to a known user ID
`webhook.test`	Test event sent from the dashboard

Payload Format

Every webhook delivery sends a JSON payload with the following structure:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "payment.completed",
  "created_at": "2026-02-19T10:00:00Z",
  "data": {
    "user_id": "user-123",
    "product_id": "premium_monthly",
    "transaction_id": "2000000123456789",
    "subscription_id": "8f14e45f-ceea-4b1c-9c3a-5d2a7f0c1e11",
    "price": 9.99,
    "currency": "USD",
    "platform": "ios"
  }
}

Field	Type	Description
`id`	`string (uuid)`	Unique event identifier
`type`	`string`	One of the 16 supported event types
`created_at`	`string (datetime)`	ISO 8601 timestamp of when the event occurred
`data`	`object`	Event-specific payload (varies by event type)

Payment completed data

Field	Description
`transaction_id`	The store’s id of the charge: the App Store `transactionId`, or the Google Play order id as Play reports it when the notification is processed. A Google Play notification processed after a later renewal carries that later order’s id.
`subscription_id`	The AppDNA subscription id, the same for every charge of the subscription, including an App Store upgrade, downgrade or crossgrade. A Google Play upgrade or downgrade creates a new purchase token, which AppDNA records as a new subscription with a new `subscription_id`; the previous one is not linked to it.
`product_id`	The product charged. For an App Store transaction reported after a later one, this is that transaction’s own product.
`price`	The price the store reported for the charge: the App Store transaction’s `price`, or the plan’s recurring price from Google Play. If the store reported no price, this is the price last recorded for the same product on this subscription. It is `null` when no price is known, for example after a product change, or for an App Store transaction reported after a later one without a price.
`currency`	The ISO 4217 code the store reported, trimmed and upper-cased. It is `null` whenever `price` is `null`, and when the store reported a price without a currency.
`platform`	`ios` or `android`.
`environment`	`production` or `sandbox`: `sandbox` for an App Store Sandbox notification or a Google Play license-tester purchase. `payment.failed` and `subscription.canceled` carry it too.

A store-driven webhook is recorded in the same database write as the store notification it belongs to, and handed to webhook delivery once that write has committed: on the App Store before AppDNA’s other follow-up work (the entitlement sync and the internal billing event), on Google Play after the entitlement sync and before the internal events. It is marked sent only when its delivery records are stored, so it is not lost when the hand-off or the work after it fails: the store redelivers the notification and a webhook still pending is handed off then. This is at-least-once: if the hand-off succeeded but marking it sent did not, the redelivery hands it off again, as a new delivery with a new id — so your endpoint can, rarely, see the same store event twice (for payment.completed, the same data.transaction_id), never none — unless it is still undelivered 24 hours after it was recorded, or every allowed attempt was started and the last one never finished, in which case it is marked failed (see Retry Policy) and can be retried by hand. Purchases that reach AppDNA only through an inbound provider webhook (RevenueCat, Adapty and similar) send no payment.completed.

Changed in the September 2026 server release. payment.completed differs from the previous release in its payload and in which charges send it, and payment.failed and subscription.canceled changed too.payment.completed payload:

data.transaction_id was the AppDNA subscription id, the same for every renewal. It is now the store’s transaction id: the App Store transactionId, or the Google Play order id.
data.subscription_id is new: the AppDNA subscription id that transaction_id used to carry.
data.price is null when no price is known. It was 0.
data.currency is null when price is null or the store reported no currency. It was USD when no currency was recorded.
For an App Store transaction reported after a later one, product_id, price and currency are that transaction’s own. They were the subscription’s current ones.

Now sent: an App Store resubscribe, an App Store paid offer that starts, restarts or immediately upgrades a subscription, and a Google Play subscription recovering from account hold.No longer sent: a free-trial start, a scheduled App Store downgrade (or any App Store renewal-preference change other than an immediate upgrade), an App Store transaction whose price is 0, a Family Sharing member’s access, a Google Play charge notification processed after Play has moved the subscription to grace period, account hold, paused or expired, and a Google Play renewal or purchase notification processed while the subscription is revoked or refunded in AppDNA.Google Play:

A notification whose purchase token Google Play answers with 400, 404 or 410 now sends nothing. It used to be processed from the notification data alone, and could send a webhook only when AppDNA already had the subscription (or the notification was a new purchase for a package name with an active Google Play credential).
A notification for a purchase token that belongs to another app, or one AppDNA cannot attribute to a single app (no ?app= on the push endpoint and several apps share the package name), now sends nothing.
What a notification answers now depends on the app’s Google Play credential. In each of these cases it used to be processed from the notification data alone, and could send a webhook only when AppDNA already had the subscription (or the notification was a new purchase for a package name with an active Google Play credential):
- The app has a Google Play credential, but its service-account JSON is missing, invalid or incomplete: 5xx, so Pub/Sub keeps redelivering the notification until the credential is fixed.
- The push endpoint carries ?app= and that app has no active Google Play credential: 404.
- The push endpoint has no ?app= and no app’s active Google Play credential has the notification’s package name: 200, and the notification is dropped.
payment.completed product_id follows the product of Google Play’s current line item. It used to stay the product already on the subscription: the one the app last verified, or, for a subscription first seen through a Play purchase notification, that notification’s subscriptionId. A Play notification never changed it.

payment.failed:

It is no longer sent for an App Store notification about a transaction older than the one the subscription already carries.
A Google Play SUBSCRIPTION_REVOKED sends it only when Play confirms the subscription is expired. It was sent for every revoke.

subscription.canceled:

It is now sent for the App Store too: DID_CHANGE_RENEWAL_STATUS / AUTO_RENEW_DISABLED. It was Google Play only.
It is sent only when Play’s state agrees: canceled, expired, or active with auto-renew off. It was sent for every SUBSCRIPTION_CANCELED.
data.cancel_reason can now be canceled. It was always voluntary.
data.effective_date is kept from when AppDNA first recorded auto-renew as off. It was the time the notification was processed.

All three billing webhooks now carry data.environment (production or sandbox). A Sandbox App Store purchase used to send payment.completed with nothing telling it apart from a production one.To detect a redelivered webhook, use the event id, which stays the same on every retry of a delivery.

Request Headers

Every webhook request includes the following headers:

Header	Description
`Content-Type`	`application/json`
`X-AppDNA-Signature`	HMAC-SHA256 signature for verification
`X-AppDNA-Event`	Event type (e.g., `payment.completed`)
`X-AppDNA-Delivery-Id`	Unique delivery identifier for deduplication
`X-AppDNA-Timestamp`	Unix timestamp of when the request was sent
`User-Agent`	`AppDNA-Webhooks/1.0`

Signature Verification

Every webhook request is signed with your endpoint secret using HMAC-SHA256. Always verify the signature before processing the payload. The signature is sent in the X-AppDNA-Signature header in the format:

X-AppDNA-Signature: sha256=<hex-encoded-signature>

The signing input is the raw JSON stringified request body.

Node.js
Python

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const providedSignature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(providedSignature, 'hex')
  );
}

// Express.js example
app.post('/webhooks/appdna', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-appdna-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.APPDNA_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  console.log(`Received ${event.type}:`, event.data);

  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    provided = signature.replace('sha256=', '')

    return hmac.compare_digest(expected, provided)

# Flask example
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks/appdna', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-AppDNA-Signature', '')
    payload = request.get_data()

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        abort(401)

    event = request.get_json()
    print(f"Received {event['type']}: {event['data']}")

    return 'OK', 200

Always use constant-time comparison (e.g., crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python) when verifying signatures. Simple string comparison is vulnerable to timing attacks.

Retry Policy

If your endpoint returns a non-2xx response or times out, AppDNA retries the delivery with exponential backoff:

Retry	Delay
1st	30 seconds
2nd	2 minutes
3rd	10 minutes
4th	1 hour

Maximum retries: 5 attempts total (1 initial delivery + 4 retries). A delivery whose first attempt never started (the AppDNA process that recorded it stopped before sending it) is sent by the retry schedule once it has waited 5 minutes, and that send is its first attempt; if the process stopped in the middle of the first send, the retry schedule’s send is its second. The attempts toward the 5 are counted like this: the first when the delivery is recorded, each retry when it is scheduled after a failed attempt, and a send that the sending process stopped in the middle of when the retry schedule picks the delivery up again — so such a send still counts, and no delivery is ever sent more than 5 times: once all 5 have started and the last one never finished, the delivery is marked failed. One AppDNA process sends a given attempt: it re-confirms that it still holds the delivery just before sending and records the result only while it still does, so two overlapping retry runs never send the same delivery twice. A test delivery (sent once, never retried) whose one send recorded no answer is marked failed after 5 minutes. The delivery log shows the attempt the delivery is on, or waiting for, as n/5 (a test delivery, sent once and never retried, as 1/1). One that is still pending or waiting to retry 24 hours after it was recorded or last retried by hand is marked failed too, instead of being delivered late. Either way the reason is in its delivery log, and it says which case it was: never sent (Never sent: …), attempted and still waiting to retry (Given up: attempted, and still waiting …), attempted with the last attempt never finished, so there is no answer to show (Given up: attempted, and the last attempt never finished …), or out of attempts (Given up: every allowed attempt was started, … or Given up: no attempt is left, …); retry it by hand to send it (that starts a new 5 attempts and a new 24 hours). Delivery timeout: 30 seconds, for the request and reading the response body. If your server does not respond within 30 seconds, the delivery is marked as failed and scheduled for retry; a response whose status arrived in time but whose body did not finish is judged by its status, with an empty body in the delivery log. Maximum response body logged: 10 KB. Response bodies exceeding this limit are truncated in delivery logs.

After 50 consecutive delivery failures, the webhook endpoint is automatically disabled. You can re-enable it from the dashboard or via the API.

Management API

All management endpoints require Customer JWT authentication (Authorization: Bearer header).

List Endpoints

GET /api/v1/webhooks/endpoints

Returns all configured webhook endpoints for the current application. The signing secret is never returned (only once, by create and rotate-secret), and every custom header value is shown as ••••••; header names are kept.

Create Endpoint

POST /api/v1/webhooks/endpoints

Request body:

{
  "name": "Production Backend",
  "url": "https://api.example.com/webhooks/appdna",
  "events": ["payment.completed", "payment.failed", "subscription.canceled"],
  "description": "Handles payment lifecycle events",
  "headers": {
    "X-Custom-Header": "custom-value"
  }
}

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable endpoint name
`url`	`string`	Yes	Destination URL (HTTPS required)
`events`	`string[]`	Yes	Array of event types to subscribe to
`description`	`string`	No	Optional description
`headers`	`object`	No	Custom headers to include in deliveries. Their values are never returned by the API (shown as `••••••`)

Webhook URLs must use HTTPS: an http:// URL is rejected with 400. The host must resolve to a public internet address: a URL with credentials in it, a private, loopback or link-local address, an internal host name, or a host that does not resolve is refused when you create the endpoint, with 422 and error.code WEBHOOK_URL_NOT_PUBLIC, and the message names the reason. The same check runs again before every delivery, since a host’s DNS can change after you register it; a delivery it refuses is recorded as failed. AppDNA does not follow redirects: a 3xx response counts as a failed delivery.

Update Endpoint

PATCH /api/v1/webhooks/endpoints/{id}

Update any field on an existing endpoint. Partial updates are supported. headers replaces the stored set: a header whose value is •••••• (as the API returns it) keeps its stored value, a new value replaces it, and a header left out is removed; •••••• for a header that has no stored value is rejected with 400. A new url is checked as on create (422 WEBHOOK_URL_NOT_PUBLIC when it does not resolve to a public HTTPS address); an update that leaves the URL unchanged is not re-checked.

Delete Endpoint

DELETE /api/v1/webhooks/endpoints/{id}

Permanently deletes the endpoint and all associated delivery history.

Test Endpoint

POST /api/v1/webhooks/endpoints/{id}/test

Sends a webhook.test event to the endpoint. Use this to verify your endpoint is reachable and correctly verifying signatures.

Rotate Signing Secret

POST /api/v1/webhooks/endpoints/{id}/rotate-secret

Generates a new signing secret for the endpoint. The previous secret is immediately invalidated.

After rotating a secret, update your server’s verification code with the new secret before the next delivery attempt.

Disable Endpoint

POST /api/v1/webhooks/endpoints/{id}/disable

Temporarily disables the endpoint. No deliveries are attempted while disabled. Events that occur during this period are not queued.

Enable Endpoint

POST /api/v1/webhooks/endpoints/{id}/enable

Re-enables a previously disabled endpoint.

List Deliveries

GET /api/v1/webhooks/endpoints/{id}/deliveries

Returns a paginated list of delivery attempts for the endpoint, including status, response code, and timestamps.

Delivery Detail

GET /api/v1/webhooks/deliveries/{id}

Returns full details for a specific delivery attempt, including request/response headers and body. In the recorded request headers the signature and every custom header value are shown as ••••••; AppDNA’s own headers (Content-Type, X-AppDNA-Event, X-AppDNA-Delivery-Id, X-AppDNA-Timestamp, User-Agent) are shown as sent.

Retry Failed Delivery

POST /api/v1/webhooks/deliveries/{id}/retry

Manually retries a failed delivery. The retry is attempted immediately, independent of the automatic retry schedule.

Event Catalog

GET /api/v1/webhooks/events

Returns the full list of supported webhook event types with descriptions.

Your webhook integration is working correctly when you receive a webhook.test event at your endpoint and can successfully verify the signature.

​Overview

​Supported Event Types

​Payload Format

​Payment completed data

​Request Headers

​Signature Verification

​Retry Policy

​Management API

​List Endpoints

​Create Endpoint

​Update Endpoint

​Delete Endpoint

​Test Endpoint

​Rotate Signing Secret

​Disable Endpoint

​Enable Endpoint

​List Deliveries

​Delivery Detail

​Retry Failed Delivery

​Event Catalog

Overview

Supported Event Types

Payload Format

Payment completed data

Request Headers

Signature Verification

Retry Policy

Management API

List Endpoints

Create Endpoint

Update Endpoint

Delete Endpoint

Test Endpoint

Rotate Signing Secret

Disable Endpoint

Enable Endpoint

List Deliveries

Delivery Detail

Retry Failed Delivery

Event Catalog