Webhooks

Register

An org holds at most 20 active endpoints. The signing secret starts with whsec_ and is in the response of the registration and nowhere else, so store it then.

Proved by webhooks.register

What is sent

Each attempt is a POST of the event envelope as JSON, abandoned when the connection is idle for 10 seconds, with redirects not followed (a 3xx is a failure). Any 2xx is success and its body is ignored. Dedupe by the envelope id: a delivery can arrive more than once.

Proved by webhooks.signature

Verify the signature

v1 is the lowercase hex HMAC-SHA256, keyed with the endpoint secret, of the timestamp, a dot, and the exact bytes received, before any JSON parsing. Reject a timestamp more than 300 seconds from your clock. A retry is signed afresh, so its timestamp is its own. Ignore fields other than t and v1, so a later version does not break a receiver.

Node

const crypto = require("node:crypto");

function verify(secret, header, rawBody) {
  const fields = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = Number(fields.t);
  if (!Number.isInteger(timestamp) || !fields.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = Buffer.from(fields.v1);
  const wanted = Buffer.from(expected);
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

Python

import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(","))
    if "t" not in fields or "v1" not in fields or not fields["t"].isdigit():
        return False
    timestamp = int(fields["t"])
    if abs(time.time() - timestamp) > 300:
        return False
    message = str(timestamp).encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields["v1"])

Proved by webhooks.signature

Retries

A delivery makes at most 6 attempts over about 14.6 hours. Each attempt records its number before it sends, so a delivery is never tried again without its counter moving.

A delivery is one of pending, delivered, failed. It ends failed after the last attempt, when its endpoint was disabled, when its event passed the 90 days retention, or when an attempt began and never reported back for 5 minutes. A failed delivery keeps lastStatusCode and a lastError of at most 200 characters, never the body your server answered.

Stated, not run by the suite: webhooks.retry

Why an endpoint is disabled

An endpoint lives only as long as the key that created it. A disabled endpoint lists a disabledReason:

A live key holding webhook:manage brings an endpoint back with POST /v1/webhooks/{id}/enable, which also rebinds it to that key. A retry already waiting when an endpoint is disabled fails with The endpoint was disabled when its attempt runs, unless the endpoint was enabled again first.

Stated, not run by the suite: webhooks.key_lapsed

Replay

Replay sets deliveries back to pending with a fresh series of 6 attempts. With no eventId it replays every failed delivery, at most 100. With an eventIdit replays that event's delivery whether it failed or was delivered. A delivery already pending is left alone, and a disabled endpoint answers 409.

Proved by webhooks.replay

Where a URL may point

Only https on the default port, with no credentials, whitespace or backslashes. Internal host names, wildcard DNS names, and private, loopback, link-local and cloud metadata addresses in any written form are refused at registration with 400 validation_failed on body.url. The check that counts runs again before every send: the host is resolved, every answer is judged, and the connection is pinned to the address judged, so a DNS rebind after the check cannot redirect it.

Proved by webhooks.ssrf