Webhooks

When a request reaches a final decision, AgentFlow can POST a signed approval.completed event to your connection's callback URL. Events are queued atomically with the signed proof and delivered with at-least-once semantics.

Enabling webhook deliveryCopy Anchor Link

An operator enables webhook delivery on the connection in the console (AI agents → <connection> → Delivery) and sets the HTTPS callback URL — see Using the platform → Agent connections.

The webhook signing secret is shown once — when webhooks are first enabled. It is never retrievable afterward; store it immediately. Rotating the secret from the connection page does not invalidate in-flight events, because each event is signed with the secret that was live when it was queued.

The callback URL must be https:// — non-HTTPS callbacks are rejected at configuration time, before any delivery is attempted.

The approval.completed eventCopy Anchor Link

Body (the raw bytes of this JSON are what you verify):

{
  "version": 1,
  "eventId": "evt_9f4b2c1d",
  "type": "approval.completed",
  "occurredAt": "2026-11-10T14:23:11.041Z",
  "request": {
    "id": "apr_1234_v1",
    "externalId": "REQ-1001",
    "version": 1,
    "status": "approved"
  },
  "decisionId": "di_0021",
  "receiptId": "prf_9d3a"
}

• request.status is the finalized request status (approved, rejected).
• receiptId identifies the proof; fetch the full signed receipt with getProof.
• Delivery is at-least-once — deduplicate on eventId.
• A webhook is a notification, not proof. Treat it as a trigger to call getStatus/getProof; the signed receipt is what authorizes the action.

Headers and signature verificationCopy Anchor Link

Each delivery includes:

Verification recipe:

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

function verifyAgentflowWebhook(
  rawBody: string,            // exact request body bytes
  timestamp: string,          // x-agentflow-timestamp
  signatureHeader: string,    // x-agentflow-signature: "v1=<hex>"
  secret: string,
): boolean {
  if (!signatureHeader.startsWith('v1=')) return false;
  const supplied = Buffer.from(signatureHeader.slice(3), 'hex');
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest();
  return supplied.length === expected.length &&
    timingSafeEqual(supplied, expected);
}

1. Read the raw body bytes before JSON parsing — reserialization changes the signature input.
2. Check x-agentflow-timestamp is inside your replay window (e.g. ±5 minutes) before verifying.
3. Compute HMAC-SHA256(secret, timestamp + "." + rawBody), compare hex against the v1= value with a timing-safe compare.
4. Reject (any non-2xx) on mismatch; return 2xx only after the event is durably recorded.

Endpoint constraintsCopy Anchor Link

Callback endpoints are held to strict delivery rules:

• HTTPS only. Non-HTTPS URLs are rejected at config time and at delivery time; URLs must not contain embedded credentials.
• Public addresses only. localhost, *.localhost, and any hostname resolving to a private, loopback, link-local, or reserved address is refused (forbidden_address).
• No redirects. Redirect responses are not followed; a 3xx status is a permanent delivery failure (http_3xx).
• TLS verification stays on. Certificate verification is never disabled.
• Payload cap. Event bodies larger than 64 KiB fail permanently as payload_too_large.

If you can't open a public HTTPS endpoint during development, run a tunnel (e.g. ngrok) and set its public URL as the callback — there are no localhost exceptions.

Retry policyCopy Anchor Link

Delivery error codesCopy Anchor Link

The lastErrorCode on a delivery record is one of:

Inspecting and retrying deliveriesCopy Anchor Link

Operators can inspect deliveries in the console on the connection page — each record shows the event ID, status (pending/delivered/failed), HTTP status code, attempt count, last error, and callback URL. A failed delivery can be requeued from there once you've fixed the receiver or callback URL.