Receive webhooks

Webhooks tell your server when a subscription or purchase changes, without waiting for the customer to open the app. Renewals, cancellations, expiries, and refunds all originate at the store, so a customer who never launches the app again still produces events your backend needs.

Use webhooks to keep your own database in sync. Keep server-side entitlement checks as the authority for an access decision: webhooks are a push channel, not a lock.

Create an endpoint

In Studio, open Settings → Webhooks, add an endpoint URL, and select the events to subscribe to. Copy the signing secret — it looks like whsec_ followed by 64 hex characters — and store it next to your secret key.

The same endpoint can be created from a backend:

$endpoint = $voidhash->webhooks()->createWebhookEndpoint(
    name: "production-backend",
    url: "https://api.example.com/webhooks/voidhash",
    events: ["subscription.created", "subscription.renewed", "purchase.completed"],
);

echo $endpoint["secret"]; // whsec_...

The URL must be http: or https: and at least one event is required. Unknown event names are rejected.

Event catalog

Payload shape

The HTTP body is the bare JSON payload — there is no envelope. The event name is repeated in the X-Webhook-Event header and in the payload's type field.

Every lifecycle payload carries these fields:

Subscription events add subscriptionId, status (active or canceled), providerSubscriptionId, and providerTransactionId — the two provider ids may be null.

Purchase events add purchaseId and providerTransactionId. On purchase.refunded, purchaseId is null when the refund could not be anchored to a stored purchase.

Monetary fields are { currency, grossAmount } with grossAmount in minor units, or null when the provider event reported no amount. null means "not reported" and is deliberately not zero-filled.

{
  "type": "subscription.renewed",
  "projectId": "proj_...",
  "personId": "person_...",
  "distinctId": "user_123",
  "productId": "prod_...",
  "productSlug": "monthly",
  "providerProductId": "com.example.monthly",
  "provider": "apple-app-store",
  "environment": "production",
  "occurredAt": "2026-08-20T09:12:44.000Z",
  "subscriptionId": "sub_...",
  "status": "active",
  "providerSubscriptionId": "1000000123456789",
  "providerTransactionId": "1000000987654321",
  "startsAt": "2026-08-20T09:12:44.000Z",
  "expiresAt": "2026-09-20T09:12:44.000Z",
  "renewedAt": "2026-08-20T09:12:44.000Z",
  "isTrial": false,
  "amount": { "currency": "USD", "grossAmount": 999 }
}

Verify the signature

Voidhash signs every request and sends three headers:

The HMAC key is the raw UTF-8 endpoint secret. The signature covers the exact bytes that were sent, so the request body must not be decoded into an array before verification — use file_get_contents("php://input") (or your framework's raw-body accessor), never $_POST.

use Voidhash\Webhook;
use Voidhash\SignatureVerificationException;

$app->post("/webhooks/voidhash", function (Request $request, Response $response) {
    $payload = (string) file_get_contents("php://input");

    try {
        $event = Webhook::constructEvent(
            payload: $payload,
            signatureHeader: $request->getHeaderLine("X-Webhook-Signature"),
            timestampHeader: $request->getHeaderLine("X-Webhook-Timestamp"),
            secret: getenv("VOIDHASH_WEBHOOK_SECRET"),
        );
    } catch (SignatureVerificationException) {
        // "missing_header" | "invalid_signature"
        // | "timestamp_out_of_tolerance" | "invalid_payload"
        return $response->withStatus(400);
    }

    // Acknowledge fast, then do the work out of band.
    handleEventAsync($event);

    return $response->withStatus(200);
});

constructEvent returns an associative array with type, payload, and timestamp keys. Event names added after your library release pass through as plain strings in $event["type"], so always give your match on the type a default arm.

Replay protection

The helper rejects a timestamp more than 300 seconds away from the current time, in either direction. Pass toleranceSeconds if your infrastructure adds delay, and pass now (a Unix timestamp) to make tests deterministic:

$event = Webhook::constructEvent(
    payload: $payload,
    signatureHeader: $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"],
    timestampHeader: $_SERVER["HTTP_X_WEBHOOK_TIMESTAMP"],
    secret: getenv("VOIDHASH_WEBHOOK_SECRET"),
    toleranceSeconds: 600,
);

Keep server clocks synchronized. Clock drift is the most common cause of timestamp_out_of_tolerance on an otherwise correct integration.

Delivery semantics

Lifecycle events are emitted only when a state transition actually happened, after the database transaction that produced it has committed. A redelivered store notification collapses on the purchase ledger's idempotency key before any event is built, so one real transition produces one event per subscribed endpoint.

Delivery itself is at-least-once. A handler that is slow, or that succeeds but fails to respond in time, is delivered again:

• A delivery is attempted up to 5 times.
• After a failed attempt the next one is scheduled 5 minutes, then 30 minutes, then 2 hours, then 24 hours later.
• Any response outside 2xx, or a response slower than 30 seconds, counts as a failed attempt.
• After the fifth failed attempt the delivery is marked exhausted and is not retried again.

Make your handler idempotent. The payloads carry stable identifiers — key on type plus subscriptionId or purchaseId plus occurredAt, record what you have processed, and ignore repeats.

Return 200 as soon as the signature verifies, then process asynchronously. In PHP-FPM land that usually means enqueueing a job; under Swoole or RoadRunner you can spawn a coroutine. A handler that does real work inline is the usual reason a delivery times out and is duplicated.

Deliveries and their per-attempt history are visible in Studio, and readable through listWebhookDeliveries, getWebhookDelivery, and retryWebhookDelivery on the webhooks resource.

Test an endpoint

Choose Send Test from an endpoint's actions menu in Studio, or call the API:

$voidhash->webhooks()->testWebhookEndpoint(endpointId: "wh_ep_...");

This sends a test.ping delivery with the body { "message": "This is a test webhook delivery", "timestamp": "..." }. It is signed exactly like a real event, so it is the fastest way to confirm that your signature verification, routing, and response time are correct before any money is involved.

Rotate a secret

Rotate immediately if a secret is exposed:

$endpoint = $voidhash->webhooks()->rotateWebhookSecret(endpointId: "wh_ep_...");

echo $endpoint["secret"]; // new whsec_...

Rotation applies to deliveries created after it. A delivery that was already queued keeps the secret it was signed with, so its retries still arrive under the old one. Have the handler accept both secrets across the rotation window, then drop the old secret once pending retries have drained.

Next steps

• Check access from your backend
• Webhook endpoints in the API reference