Webhooks

Verify, retry, and replay batch and monitor events.

Batches send a final-status event. Monitors send change.detected by default and can also send run.completed. Use a public HTTP(S) receiver and enable retries explicitly.

Configure delivery

{"webhook":{"url":"https://app.example.com/webhooks/context","retry":{}}}

Omitting retry means best-effort delivery. Store the batch’s webhook_secret from the submit response; it is returned only there. A monitor’s webhook.secret is visible with Manage permission.

Slack and GovSlack incoming-webhook URLs receive formatted messages instead of the JSON event envelope.

Verify signatures

X-Context-Signature contains t=<unix>,v1=<hex>. Compute HMAC-SHA256 over the timestamp, a period, and the unmodified raw request body, using the webhook secret. Compare in constant time and reject stale timestamps. Each attempt gets a new signature.

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

function verifyWebhook(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map(part => part.trim().split("=")));
  if (!/^\d+$/.test(parts.t ?? "") || !/^[a-f0-9]{64}$/i.test(parts.v1 ?? "")) return false;
  const timestamp = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.`).update(rawBody).digest();
  const actual = Buffer.from(parts.v1, "hex");
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

Verify before parsing JSON. Use X-Context-Id as the stable event deduplication key, including across retries and replays. X-Context-Event, X-Context-Delivery-Id, and X-Context-Attempt identify the event and attempt.

Acknowledge and retry

Return any 2xx response within 15 seconds. Persist or enqueue verified events before acknowledging, then process them asynchronously. Redirects are not followed.

retry: {} uses delays of 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 16 hours, with up to 10% jitter. A custom delays_seconds list permits up to ten delays of 1–86,400 seconds, totaling at most 72 hours. An empty list disables automatic retries.

Network errors, 408, 429, and 5xx responses are retryable. Other 4xx and 3xx responses are final. Retry-After is honored.

Delivery history and replay

Search deliveries by source and status, then inspect attempts. Delivery history lasts 30 days. Manual replay is available for seven days after the event; expired replay returns 410.

Retry a delivery resends its original payload using the source’s current URL and signing secret. Use force: true for a delivery that already succeeded. A source that was deleted or no longer has a webhook cannot be replayed. An optional idempotency key avoids duplicate replay requests.

Batch payloads retain their original download links, which expire after 24 hours. Retrieve fresh links while the result files remain available; batch files expire after seven days.

Permissions and rotation

Read operations need the source’s batches:read or monitors:read; retries need its write scope. A monitor URL change regenerates its secret. Secret rotation takes effect immediately; update the receiver after the call returns and replay rejected events when needed. See monitor events.