Outbound Webhooks

Use outbound webhooks when your backend needs to react after AppActor has verified and normalized a purchase event. This is different from Apple App Store Server Notifications and Google RTDN. Store notifications flow into AppActor. AppActor outbound webhooks flow from AppActor to your server after AppActor has processed the event.

When to use webhooks

Use webhooks for backend work such as:

granting or revoking server-side credits
syncing subscription state into your own user table
sending lifecycle emails or CRM events
unlocking backend-only premium resources
reconciling refunds, billing issues, grace periods, and renewals

Do not use webhooks as the only in-app access check. Mobile apps should still read CustomerInfo from the SDK, and backend routes should call AppActor with a secret key when they need synchronous access decisions. Sanitized outbound webhook delivery evidence

Sanitized outbound webhook delivery evidence

Setup path

Create an HTTPS endpoint on your backend.
Configure the app-level webhook URL and secret for the AppActor app.
Verify the X-AppActor-Signature header before trusting the payload.
Store eventId or X-AppActor-Delivery to make processing idempotent.
Return a 2xx response only after your handler has durably accepted the event.
Test with sandbox purchases, renewals, cancellations, refunds, billing retry, and replayed deliveries.

App-level signed webhooks receive processed lifecycle events for the app. Event-type filtering belongs to integration connections; app-level signed webhooks are the signed backend callback path documented on this page.

Webhook URLs must use a public DNS hostname over HTTPS on standard port 443. AppActor rejects userinfo, IP literals, localhost or metadata hosts, private or reserved DNS answers, DNS failures, and private-network targets to avoid SSRF and DNS-rebinding risks.

Payload shape

Every delivery uses this envelope:

Webhook payload

{
  "eventType": "subscription.renewed",
  "eventId": "f16a4b42-4db1-4a83-9876-41f9b9f51e74",
  "createdAt": "2026-05-29T14:25:31.000Z",
  "data": {
    "appId": "app_...",
    "appactorUserId": "user_123",
    "environment": "sandbox",
    "store": "apple",
    "productId": "com.example.fitness.pro_monthly",
    "appactorTransactionId": "txn_...",
    "storeTransactionId": "2000000123456789",
    "isTrialConversion": false
  }
}

The data object contains the normalized store event plus AppActor processing fields, and it depends on the event type. Treat the top-level eventType, eventId, and createdAt fields as the stable delivery envelope, then version your own handler around the fields you consume inside data.

Headers

Header	Meaning
`X-AppActor-Signature`	HMAC signature in the form `t=<unix_seconds>,sha256=<hex>`.
`X-AppActor-Signature-Version`	Signature version. Current value is `v1`.
`X-AppActor-Event`	Same event type as `payload.eventType`.
`X-AppActor-Delivery`	Unique delivery ID for this webhook attempt chain.

Verify signatures

AppActor signs timestamp + "." + rawRequestBody with HMAC-SHA256 and your webhook secret.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyAppActorWebhook(rawBody: string, signatureHeader: string, secret: string) {
  const parts = signatureHeader.split(',');
  const timestampPart = parts.find((part) => part.startsWith('t='));
  const signaturePart = parts.find((part) => part.startsWith('sha256='));

  if (!timestampPart || !signaturePart) return false;

  const timestamp = Number.parseInt(timestampPart.slice(2), 10);
  if (!Number.isFinite(timestamp)) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) return false;

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = `sha256=${createHmac('sha256', secret).update(signedPayload).digest('hex')}`;

  const expectedBytes = Buffer.from(expected);
  const receivedBytes = Buffer.from(signaturePart);

  return expectedBytes.length === receivedBytes.length && timingSafeEqual(expectedBytes, receivedBytes);
}

Verify against the raw request body, not a parsed-and-reencoded JSON object. Reformatting JSON changes the bytes and invalidates the signature.

Retries and idempotency

AppActor delivery jobs run up to 5 attempts. Failed attempts are retried with this backoff schedule:

Failed attempt	Next retry delay
1	30 seconds
2	2 minutes
3	10 minutes
4	30 minutes

The retry policy also has a 2-hour fallback delay if the delivery attempt limit is extended later. A delivery is considered successful when your endpoint returns a 2xx response. Network errors, timeouts, private-network resolution, and non-2xx responses are treated as failures. Make your handler idempotent:

store eventId for lifecycle idempotency
store X-AppActor-Delivery for delivery-attempt debugging
do not grant credits twice if the same eventId is delivered again
return 2xx after your job is safely queued if downstream work is asynchronous
return non-2xx only when you want AppActor to retry

Delivery troubleshooting

Symptom	What to check
Signature verification fails	Verify against the raw request body and use the current app webhook secret.
Delivery retries repeatedly	Check non-`2xx` responses, handler timeouts, and whether your endpoint accepts public HTTPS traffic.
Delivery rejected before send	Use a public DNS hostname on HTTPS port 443 with no userinfo or IP literal, and make sure every DNS answer is public.
Duplicate side effects	Dedupe by `eventId`; use `X-AppActor-Delivery` only for delivery debugging.
Backend needs only some event types	Use your handler to branch on `eventType`, or configure event-filtering through integration connections when that is the desired delivery path.

Common event types

Event type	Typical use
`subscription.purchased`	First subscription purchase.
`subscription.renewed`	Paid renewal or recovered renewal.
`subscription.canceled`	Cancellation while access may still remain active until expiry.
`subscription.billing_issue`	Billing retry or grace-period state.
`subscription.expired`	Subscription access ended.
`subscription.refunded`	Subscription refund or revoke.
`subscription.revoked`	Google voided subscription purchase.
`purchase.completed`	One-time in-app purchase completed.
`purchase.refunded`	One-time purchase refunded.

The AppActor event name is the normalized lifecycle type. Store-specific Apple notification types and Google RTDN notification numbers are visible in raw event details, but your webhook handler should branch on the normalized AppActor event type.

Test before launch

Before production, verify:

Apple test notification is healthy for iOS apps.
Google RTDN test notification is healthy for Android apps.
A sandbox purchase creates a customer, transaction, and active entitlement.
Your webhook endpoint receives subscription.purchased or purchase.completed.
Your handler verifies X-AppActor-Signature.
Duplicate delivery of the same eventId does not duplicate side effects.
Refund, cancellation, renewal, billing retry, and expiration paths are handled.

If your backend needs an immediate yes/no access decision, use Server-side Access Checks. Use webhooks for async lifecycle reactions.

Overview

Configure Products

Notifications & Webhooks

Outbound Webhooks

When to use webhooks

Setup path

Payload shape

Headers

Verify signatures

Retries and idempotency

Delivery troubleshooting

Common event types

Test before launch

​When to use webhooks

​Setup path

​Payload shape

​Headers

​Verify signatures

​Retries and idempotency

​Delivery troubleshooting

​Common event types

​Test before launch

When to use webhooks

Setup path

Payload shape

Headers

Verify signatures

Retries and idempotency

Delivery troubleshooting

Common event types

Test before launch