Receiving webhooks
Every customer-visible platform event (message lifecycle, suppression changes, domain verification and the webhook endpoint's own lifecycle) can be delivered to HTTPS endpoints you register. You manage endpoints through the API or the panel; delivery, retries and signing run on managed infrastructure, and this guide covers what your receiver must do and what the platform guarantees. The event types you can subscribe to, with the JSON Schema of each, are listed in the event type catalog (GET /v1/webhooks/event-types).
Register an endpoint
Create an endpoint in the panel (Webhooks, New endpoint) or with POST /v1/webhooks/endpoints: an HTTPS URL, an optional description and the event types you want (exact catalog types such as email.delivered.v1). The response includes the endpoint id. Every endpoint has its own signing secret: read it once with GET /v1/webhooks/endpoints/{endpoint_id}/secret and store it in your secret manager. The platform never shows it in logs, and you can rotate it at any time.
- URLs must be
https, at most 2 KiB, printable ASCII (use the punycode form of an international domain), without user name or password. - Addresses in private, loopback, link-local or metadata ranges are refused when the endpoint is created and whenever its URL changes; the answer does not say which address matched.
- Subscriptions are exact event types (no wildcards), at most 128 per endpoint; internal platform events are not available.
- An account has at most 10 endpoints by default (your plan may differ).
- An account sends at most 30 endpoint create requests per hour.
- An endpoint takes at most 20 changes per hour, an account 200: a resume, a URL change, a subscription set or pausing one event type.
- Pausing a whole endpoint is never limited; if a URL change cannot wait for the next hour, delete the endpoint and create it again (a new id and signing secret).
What you receive
Each delivery is a POST with a JSON body and three headers. The body is the catalog event as the producer emitted it:
| Field | Meaning |
|---|---|
id | The event id (evt_...), unique and time-ordered. Use it to deduplicate. |
type | The event type, for example email.delivered.v1. |
occurred_at | When the event happened (RFC 3339, UTC). Use it, not the arrival time, to order events. |
tenant_id | Your account id. |
stream_id | The stream of a sending event, when there is one. |
subject | What the event is about: { "kind": "message", "id": "msg_..." } for message events, { "kind": "webhook_endpoint", "id": "wh_..." } for endpoint events. |
data | The event payload exactly as the producing product wrote it. It carries ids and hashes (for example message_id, recipient_hash), never an address, a subject or a body. |
test | true on test events only. |
The headers follow the Standard Webhooks specification:
| Header | Meaning |
|---|---|
webhook-id | The delivery service's message id. It stays the same across retries of one delivery; deduplicate on the body id, not on this header. |
webhook-timestamp | Unix seconds when this attempt was signed. |
webhook-signature | One or more space-separated signatures, each v1,<base64>. Several appear while a rotated secret is still valid. |
Answer with any 2xx status within 15 seconds to acknowledge, and do your real work after acknowledging. Anything else, a timeout or a connection error counts as a failed attempt.
Verify every delivery
Verify the signatures over the raw request body, byte for byte, before you parse it: a body re-serialized by a framework no longer matches. The signed content is <webhook-id>.<webhook-timestamp>.<raw body>, the key is the base64 part of your secret after the whsec_ prefix, the algorithm is HMAC-SHA256, and the result is compared in constant time against each v1 signature. Refuse a timestamp more than five minutes away from your clock: it stops replays of captured requests. Reject anything that fails.
Any Standard Webhooks library does this for you (standardwebhooks on npm and PyPI, and libraries for most languages). Without a library, in Node.js:
`js verify-example import { createHmac, timingSafeEqual } from 'node:crypto';
/** Returns the parsed event when a v1 signature matches; throws otherwise. */ export function verifyWebhook(secret, headers, rawBody, toleranceSeconds = 300) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatures = headers['webhook-signature']; if (!id || !timestamp || !signatures) throw new Error('missing webhook headers'); const sentAt = Number(timestamp); if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > toleranceSeconds) { throw new Error('webhook timestamp outside the tolerance'); } const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64'); const expected = createHmac('sha256', key).update(${id}.${timestamp}.${rawBody}).digest(); for (const candidate of signatures.split(' ')) { const [version, value] = candidate.split(','); if (version !== 'v1' || !value) continue; const given = Buffer.from(value, 'base64'); if (given.length === expected.length && timingSafeEqual(given, expected)) return JSON.parse(rawBody); } throw new Error('no valid webhook signature'); } `
In Python:
`python verify-example import base64, binascii, hashlib, hmac, json, time
def verify_webhook(secret, headers, raw_body, tolerance_seconds=300): """Returns the parsed event when a v1 signature matches; raises otherwise.""" msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not msg_id or not timestamp or not signatures: raise ValueError("missing webhook headers") if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance_seconds: raise ValueError("webhook timestamp outside the tolerance") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = hmac.new(key, signed, hashlib.sha256).digest() for candidate in signatures.split(" "): version, _, value = candidate.partition(",") if version != "v1" or not value: continue try: given = base64.b64decode(value, validate=True) except (binascii.Error, ValueError): continue # a malformed candidate never hides a valid one after it if hmac.compare_digest(given, expected): return json.loads(raw_body) raise ValueError("no valid webhook signature") `
Read the raw body before any JSON middleware runs (in Express, express.raw({ type: 'application/json' }) on the webhook route), and keep the secret in your secret store, never in code.
Retries, duplicates and what is up to you
- Subscribed events, at least once. An event of a type your endpoint subscribes to is delivered while the endpoint and the type are active, unless the event log records it as skipped (the daily volume cap, a paused account) or failed (refused by the delivery service); a failed delivery stays visible there. Retries can deliver the same event more than once: an idempotent receiver keeps a short-lived set of the body
idvalues it has seen. - No ordering across events. Deliveries can arrive out of order, especially after retries. Order by
occurred_at, thenid. - Retries on a graduated schedule. A failed attempt is retried with growing delays for about a day. An endpoint that keeps failing is reported as failing (the
webhook.delivery.failed.v1event and the panel) and is eventually disabled (webhook.endpoint.disabled.v1); it receives nothing until you resume it after fixing the receiver. - Recovery. After a fix, resume the endpoint and replay its failed deliveries since a point in time:
POST /v1/webhooks/endpoints/{endpoint_id}/replay, within the last 30 days, at most 5 times per endpoint and 100 per account per hour. A replayed delivery keeps its eventid, so your deduplication still holds. When the endpoint is healthy again you receivewebhook.delivery.recovered.v1. - Test events.
POST /v1/webhooks/endpoints/{endpoint_id}/testsends a sample of any event type you can subscribe to, to that endpoint only (a paused or disabled endpoint answers 409), with"test": trueand a freshid; at most 60 per endpoint per hour, 10 per account per minute and 200 per account per day. Test events count toward the daily event limit and are not stored in the event log. - The event log.
GET /v1/webhooks/eventslists the events of the last 30 days with their delivery state, filterable by type, subject, delivery state and time; the detail route returns the delivered payload when it was stored (see the payload size below). The log starts with your first endpoint. - Pause per type. Pause an endpoint, or one event type on it, from the panel or the API; events of a paused type are not delivered and are not queued for later.
- Volume. An account receives at most 100,000 events per day by default; events past the cap are recorded in the event log as skipped.
- Payload size in the event log. The event log keeps delivered payloads up to 64 KiB; a larger event is listed with its envelope only, without
data(the delivery itself carries the full payload).
The embedded portal
The panel embeds a delivery portal (Webhooks, Portal; POST /v1/webhooks/portal answers a short-lived URL) that shows your endpoints, deliveries and attempts. The portal session is read-only: create and change endpoints in the panel or through the API, where approvals and the endpoint history apply. Endpoints that exist only at the delivery service (for example created in an earlier portal session) are not shown in the panel or the endpoint list, are not checked by the URL safety rules or the endpoint limit, and can be removed by an operator's reconciliation apply step.
Events about your endpoints
| Type | When |
|---|---|
webhook.endpoint.created.v1 | An endpoint was created. |
webhook.endpoint.disabled.v1 | An endpoint or one of its types was paused, or the endpoint was disabled after repeated failures. |
webhook.delivery.failed.v1 | An endpoint started failing (once per failing episode). |
webhook.delivery.recovered.v1 | A failing endpoint delivers again. |
Subscribe another endpoint to these types to monitor your integration.