Events and limits
Webhooks
Receive signed Standard Webhooks deliveries of the public events, verify the signature, and handle retries, failures and secret rotation.
Relay Port delivers the public events to your HTTPS endpoints as signed POST requests that follow the Standard Webhooks specification, so you learn that a target was published, failed or is unconfirmed without polling.
Create an endpoint
POST /webhook-endpoints takes a public HTTPS url and the events it receives: event types such as post.target.published, prefixes ending in .* such as post.*, or * for all. You can limit it to some brandIds or accountIds. The answer carries the endpoint's signing secret, which starts with whsec_, once: store it.
GET /event-typeslists every event type with its description.- An API key creates endpoints in its own mode, so a test key's endpoint receives the events of test posts.
POST /webhook-endpoints/{id}/testsends awebhook.testevent to check your handler.
What a delivery looks like
Each delivery carries three headers and a JSON body:
| Header | Value |
|---|---|
webhook-id |
The event id. It stays the same when a delivery is retried. |
webhook-timestamp |
When this attempt was signed, in Unix seconds. |
webhook-signature |
One or more space-separated v1,<base64> signatures. There are two while a rotated secret overlaps. |
The body is { "type", "timestamp", "data" }, and the same event is in GET /events.
Verify the signature
Verify every delivery before you trust it, against the raw body as it arrived and before you parse it:
- Drop the
whsec_prefix from the secret and base64-decode the rest: that is the HMAC key. - Join
webhook-id,webhook-timestampand the raw body with dots. - Compute HMAC-SHA256 of that string with the key, and compare it with each
v1signature in the header, in constant time. - Refuse a timestamp more than five minutes away from now, so an old delivery cannot be replayed.
This function does all four with Web Crypto, so it runs in Node.js, Deno, Bun and Cloudflare Workers:
const TOLERANCE_SECONDS = 300;
const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
const decode = (text: string) => Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
export async function verifyWebhook(secret: string, headers: Headers, body: string): Promise<boolean> {
const id = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signatures = headers.get("webhook-signature");
if (!id || !timestamp || !signatures) return false;
const sentAt = Number(timestamp);
if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SECONDS) return false;
const key = await crypto.subtle.importKey("raw", decode(secret.replace(/^whsec_/, "")), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
for (const entry of signatures.split(" ")) {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature || !BASE64.test(signature)) continue;
if (await crypto.subtle.verify("HMAC", key, decode(signature), signed)) return true;
}
return false;
}
Call it with the endpoint's secret, the request headers and the body text, and answer 401 when it returns false. During a secret rotation, the header carries a signature for each secret and one match is enough.
Answer fast, and expect repeats
- Answer with a
2xxstatus within 10 seconds, then do the work. A slower answer counts as a failure. - Delivery is at least once and in no fixed order, so the same event can arrive twice. Deduplicate on
webhook-id, and read the event'stimestamprather than the arrival order. - A failed attempt is retried 10 times, with delays that grow over about three days.
GET /webhook-endpoints/{id}/deliveriesshows every attempt with its response status, andPOST /webhook-endpoints/{id}/deliveries/{deliveryId}/retrysends one again. - An endpoint that keeps failing for 3 days becomes
failing, and after 7 days it isdisabledand the workspace's owners and admins get an email. Setstatusback toactivewithPATCH /webhook-endpoints/{id}once it is fixed.
Rotate the secret
POST /webhook-endpoints/{id}/rotate-secret returns a new secret once. For overlapHours (24 by default, at most 168) every delivery is signed with both the old and the new secret, so you can deploy the new one without dropping a delivery.