Webhooks and the signature

A webhook subscription is your https endpoint, signed and POSTed when the events you picked happen — so your systems hear about a change the moment it happens instead of polling for it. This guide is the subscription, the delivery, the signature check, and what happens when your endpoint is down.

Subscribing

Register an endpoint with createWebhookSubscription: an https address, a name, and the events you want — between one and 64 names from a universe of 540, one per thing that can happen to a kind of record, such as at.analytics.dashboard.create.ok.v1. An unknown name is refused when you subscribe, so the list you send is the list that will fire. A group may hold up to 10 active subscriptions.

The answer carries the signing secret once — store it in your receiver then and there; the platform keeps a hash and cannot show it again. Rotate it with rotateWebhookSubscriptionSecret whenever you need to: the new secret signs from that moment and the old one stops.

What a delivery carries

Deliveries are thin: id, event, occurredAt, construct — the record's type and id — revision, and subscriptionId. Nothing of the record's contents rides in the payload. Read the record back through this same API with your key, so what your receiver acts on is always the current record, read under your own permissions.

The two promises and the two duties

A delivery arrives at least once, and deliveries are unordered. Your receiver therefore has two duties: de-duplicate on the payload id, and when two deliveries concern the same record, order them by revision, never by arrival. Answer with a 2xx within 10 seconds; a redirect counts as a failure, and the response body is ignored.

Verifying the signature

Every delivery carries an almondtill-signature header of the form t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of the string <t>.<raw body> under your secret. To verify: take the raw request body exactly as received, before any parsing; join t, a dot and the body; compute the HMAC with your secret; compare it to v1 with a constant-time comparison; and reject a t older than your tolerance of a few minutes. Authenticate the signature, never the sender's address — deliveries come from shared infrastructure.

When your endpoint is down

Failed deliveries are retried. After 20 consecutive failures the subscription is suspended: fix the endpoint with updateWebhookSubscription, then bring it back with reactivateWebhookSubscription. Events missed while suspended do not replay — re-sync the records you care about through the API. Prove the whole lane at any time with pingWebhookSubscription, which sends a signed test delivery whose id is the ping id it answers.