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. A customer who never launches the app again still produces events your backend needs to know about.

Use webhooks to keep your own database in sync. For an access decision, keep server-side entitlement checks as the authority. Webhooks are a push channel, not a lock: they tell you that something changed, but they do not decide access.

Create an endpoint

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

You can also create the same endpoint from your backend. This program creates an endpoint that subscribes to three events and prints its signing secret:

endpoint, err := voidhash.Webhooks.CreateWebhookEndpoint(ctx, &voidhash.CreateWebhookEndpointParams{
    Name: "production-backend",
    URL:  "https://api.example.com/webhooks/voidhash",
    Events: []string{
        "subscription.created",
        "subscription.renewed",
        "purchase.completed",
    },
})

fmt.Println(endpoint.Secret) // whsec_...

The URL must use http: or https: and point to a public address: Voidhash rejects localhost and private or internal network addresses, and does not deliver to a host that resolves to one. You must subscribe to at least one event. Unknown event names are rejected.

Event catalog

subscription.created does not always mean a fresh purchase. Voidhash emits it the first time it sees a subscription. That is usually the subscription's start, but it can also be a renewal, for example when the start notification never reached Voidhash, or when an app migrated onto Voidhash in the middle of a subscription. In that case Voidhash delivers subscription.created first and subscription.renewed immediately after, both for the same subscriptionId. As a result, every renewal you receive refers to a subscription you have already been told about.

subscription.product_changed is sent when a subscription moves to another product before Voidhash records a charge for the change, for example a Stripe price change billed with the next invoice. Access moves to the new product at once. The product fields name the new product, and previousProductId, previousProductSlug and previousProviderProductId name the product it replaced. changedAt is when the change took effect. The period stays the same and the event carries no amount: the charge for the change arrives later as a subscription.renewed of its own. A change that arrives together with its charge, such as an App Store upgrade, is delivered only as subscription.renewed, which already names the new product.

An endpoint receives only the events it subscribes to, so an existing endpoint receives subscription.product_changed once you add it to the endpoint's events.

Payload shape

The HTTP body is the bare JSON payload, with no envelope around it. The event name appears twice: in the X-Webhook-Event header and in the payload's type field.

Every lifecycle payload carries these fields:

Subscription events add four more fields: 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 matched to a stored purchase.

subscription.expired carries an expirationReason: ended when the subscription's period or grace period ran out or the store ended it, for example after a refund, and revoked when the store took access away before the period ended, for example when a Family Sharing member loses access. Either way the person no longer has access. A revoked one-time purchase is reported as purchase.revoked.

Monetary fields such as amount have the shape { currency, grossAmount }, with grossAmount in minor units (cents rather than dollars, for example). When the provider event reported no amount, the field is null. null means the amount was not reported. Voidhash deliberately does not replace it with zero.

Here is a complete subscription.renewed payload:

{
  "type": "subscription.renewed",
  "projectId": "proj_...",
  "personId": "person_...",
  "distinctId": "user_123",
  "productId": "prod_...",
  "productSlug": "monthly",
  "providerProductId": "com.example.monthly",
  "provider": "apple-app-store",
  "source": null,
  "verified": true,
  "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 Voidhash sent, so read the body with io.ReadAll(r.Body) and verify it before anything decodes it. A framework that re-serializes the body breaks verification.

This net/http handler reads the raw body, verifies the signature, and acknowledges the delivery before doing any work:

import "github.com/voidhash/voidhash-go/webhook"

func voidhashWebhookHandler(w http.ResponseWriter, r *http.Request) {
    rawBody, err := io.ReadAll(r.Body)
    if err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    event, err := webhook.ConstructEvent(rawBody, r.Header, os.Getenv("VOIDHASH_WEBHOOK_SECRET"))
    if err != nil {
        // errors.Is(err, webhook.ErrMissingHeader)
        //        | webhook.ErrInvalidSignature
        //        | webhook.ErrTimestampOutOfRange | webhook.ErrInvalidPayload
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    // Acknowledge fast, then do the work out of band.
    go handleEvent(event)
    w.WriteHeader(http.StatusOK)
}

ConstructEvent returns a webhook.Event with Type string, Payload json.RawMessage, and Timestamp int64. Event names added after your library release pass through as plain strings in Type, so always give your switch on the type a default case. When you need a typed payload, decode it on demand with json.Unmarshal(event.Payload, &renewed).

Replay protection

Replay protection stops an attacker from re-sending a captured request later. The helper rejects a timestamp more than 300 seconds away from the current time, in either direction. If your infrastructure adds delay, raise the limit by passing options with a larger ToleranceSeconds. Set Now in the same options to make tests deterministic.

This call allows a 600 second window:

event, err := webhook.ConstructEventWithOptions(rawBody, r.Header, secret, webhook.VerifyOptions{
    ToleranceSeconds: 600,
})

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

Delivery semantics

Voidhash emits a lifecycle event only when a state transition actually happened, and only after the database transaction that produced it has committed. If a store sends the same notification twice, the purchase ledger recognizes the duplicate by its idempotency key (a stable identifier for the notification) and drops it before any event is built. One real transition therefore produces one event per subscribed endpoint.

Delivery itself is at-least-once. Voidhash delivers a webhook again when your handler is slow, or when it succeeds but fails to respond in time. The retry schedule is:

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

Because of this, your handler must do two things.

First, make it idempotent, so that processing the same event twice has no extra effect. Every payload carries stable identifiers. Build a key from type, subscriptionId or purchaseId, and occurredAt. Record each key you have processed, and ignore any event whose key you have already seen.

Second, acknowledge quickly. Return 200 as soon as the signature verifies, then process the event asynchronously. Hand the event to a worker pool or enqueue it. A handler that does real work before responding is the usual reason a delivery times out and arrives a second time.

You can see each delivery and its per-attempt history in Studio. The same data is readable through ListWebhookDeliveries, GetWebhookDelivery, and RetryWebhookDelivery on the webhooks service.

Test an endpoint

To send a test delivery, choose Send test from an endpoint's actions menu in Studio, or call the API:

voidhash.Webhooks.TestWebhookEndpoint(ctx, "wh_ep_...")

Either way, Voidhash 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

If a secret is exposed, rotate it immediately. This call generates a new secret for the endpoint and returns it:

endpoint, err := voidhash.Webhooks.RotateWebhookSecret(ctx, "wh_ep_...")

fmt.Println(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 your handler accept both secrets during 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