Webhooks

Conceptual

Lifecycle callbacks with signature verification and delivery guarantees.

Webhooks deliver task and run lifecycle events to your endpoint. Delivery is at-least-once; handlers must be idempotent.

Events#

Event	Delivered when
`task.completed`	Task reached a terminal success state
`task.failed`	Task failed non-recoverably
`task.suspended`	Budget exhausted or dependency unavailable
`approval.requested`	A human decision is required
`approval.expired`	An approval window elapsed
`run.checkpoint`	A checkpoint was written (opt-in)
`artifact.published`	A durable output became available
`policy.denied`	A tool call was denied by policy

Signature verification#

import { createHmac, timingSafeEqual } from class="tok-str">"node:crypto";

export function verify(rawBody: string, header: string, secret: string) {
  const [tsPart, sigPart] = header.split(class="tok-str">",");
  const timestamp = tsPart.slice(class="tok-num">2);
  const signature = sigPart.slice(class="tok-num">3);
class="tok-com">
  // reject anything older than five minutes
  if (Math.abs(Date.now() / class="tok-num">1000 - Number(timestamp)) > class="tok-num">300) return false;

  const expected = createHmac(class="tok-str">"sha256", secret)
    .update(class="tok-str">`${timestamp}.${rawBody}`)
    .digest(class="tok-str">"hex");

  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Retry schedule: 8 attempts with exponential backoff over 24h
Success criteria: HTTP 2xx within 10 seconds
Ordering: Not guaranteed — use sequence to order
Replay: Available for 7 days via the API

Last updated 2026-09-15