Skip to content
Relay Port

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-types lists 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}/test sends a webhook.test event 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:

  1. Drop the whsec_ prefix from the secret and base64-decode the rest: that is the HMAC key.
  2. Join webhook-id, webhook-timestamp and the raw body with dots.
  3. Compute HMAC-SHA256 of that string with the key, and compare it with each v1 signature in the header, in constant time.
  4. 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 2xx status 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's timestamp rather than the arrival order.
  • A failed attempt is retried 10 times, with delays that grow over about three days. GET /webhook-endpoints/{id}/deliveries shows every attempt with its response status, and POST /webhook-endpoints/{id}/deliveries/{deliveryId}/retry sends one again.
  • An endpoint that keeps failing for 3 days becomes failing, and after 7 days it is disabled and the workspace's owners and admins get an email. Set status back to active with PATCH /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.