Webhooks overview

Webhooks push workspace events to your endpoint as they happen — an issue created, a state changed, a comment added — so you can drive external systems without polling the API.

Verifying deliveries

Every delivery is signed with HMAC over the raw request body using your endpoint's secret. Verify the signature before trusting the payload; a request that does not verify did not come from us. Reject anything that fails the check, and always compare signatures in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery and retries

Respond with a 2xx quickly to acknowledge receipt; do the real work asynchronously. Failed deliveries are retried with backoff, so make your handler idempotent — use the event id to de-duplicate, the same way the REST API uses idempotency keys.