url, an explicit list of events, and a server-generated secret Forge uses to sign every delivery (timestamped HMAC-SHA256 in the X-Forge-Signature-V2 header). Every delivery body is the v2 event envelope — there is one body shape and nothing on the subscription changes it.
The subscription lifecycle is self-service. An External App acts on its own subscriptions. In v3, the list, update, pause, resume, test and deliveries operations also take a platform or Personal key, which reaches every subscription, admin-owned and app-owned; such a key revokes with POST /api/v3/webhooks/{webhookId}/revoke instead of DELETE. Each operation page shows both credential kinds. Each endpoint requires webhooks:read (list, deliveries) or webhooks:manage (create / update / pause / resume / test / delete / revoke / rotate-secret / replay). An External App reaches its own subscriptions only: another app’s or an unknown subscription answers 404, and a revoked one answers 409 invalid_state on every write except delete, which answers 200 again. Each operation page gives a platform or Personal key’s answers.
Subscribable event types
Subscription is scope-gated. Every event definition declares asubscriptionScope — the catalog permissions the app’s role grants must all hold (the app’s computed allowedScopes) for it to subscribe, or "admin" — and the gate runs twice: at subscribe time (400 naming the missing permissions) and again per delivery at dispatch time, so revoking a role narrows delivery immediately without touching the subscription.
The subscribable set is therefore not a fixed list; it is “every event whose scope this app holds”. "admin"-scoped events (alert.*, observability.*, runtime.*, model.deprecation.*, lifecycle.*, synthesis.*, builder.*, secret.rotation_stale) are operator-only and never app-subscribable.
"*" subscribes to every event whose scope the app holds, resolved at dispatch — giving the app a role later widens an existing * subscription without an edit. A subscription must list at least one event; an empty events array is a 400.
See Webhooks (operator guide) for the full table.
Human task events
An External App that asks a person learns the outcome from two events:human_task.completed when someone answers, and human_task.canceled when the
ask is withdrawn, reaches its due date, or everyone asked declines. Subscribing and delivery need the
app’s role grants to hold human_tasks:use. To ask at all, the app’s token must also name
human_tasks:use in its scope (for example scope=human_tasks:use webhooks:manage); a grant alone
is not enough.
The data is thin, ids only:
human_task.canceled carries cancelReason (withdrawn, due_date or declined) in place of
action. Neither carries the form’s output, a reason, or who answered. Read those with
Read one of your asks.
- Only the app that asked hears it. The envelope’s
initiatoris the app, and another app’s subscription never receives it, whatever it holds. - Operators see the ids. An admin subscription (one with no owning app), including a
*subscription, receives every app’s human task events: their task ids, client references and action ids. That is intended operator visibility, and it is why the payload carries nothing else. - A platform API key polls. A platform API key owns no subscription. Its asks’ events reach admin
subscriptions only, and the key reads its outcomes with
getRequestedHumanTask. - No event on supersede. When an app is deactivated or deleted, a key is revoked or expires, or a
grant no longer covers an ask’s home, its open asks close as
supersededand no webhook is sent: the requester can no longer receive one. The ask’s state is still readable. - A grant must cover the app’s request unit to deliver. Delivery re-checks the app’s scopes where
its requests resolve, the deployment root. An app whose
human_tasks:usecovers only a sub-unit can ask people there but hears no webhook; it pollsgetRequestedHumanTask, which works there.
Secret handling
Thesecret is returned exactly once at create-time and again at rotate-secret. Forge stores it AES-256-GCM-encrypted at rest (an enc:v1: prefix on webhookSubscriptions.secret), decrypting it only in-memory at signing time, and never re-emits it. Create and rotate-secret responses are never stored for Idempotency-Key replay, and neither runs twice under one key: a repeated create answers 201 with only the webhook’s data.id (id-only replay), and a repeated rotate-secret answers 409 idempotency_result_unavailable. Neither returns the secret again. Lose it, and the only recovery is rotate-secret. A revoked subscription cannot be rotated (409 invalid_state).
A rotation keeps the replaced secret signing webhook-signature beside the new one until previousSecretExpiresAt in the rotate response (at least 24 hours), so a receiver can switch without dropping a delivery. X-Forge-Signature-V2 uses only the new secret. A second rotation inside the window replaces the old secret: at most two are live. See Rotating the secret.
Operations
Replay a delivery
webhooks:manage permission. Ownership is enforced server-side off the authenticated principal.
The original delivery this replay was created from, mirrored onto the new row’s
replayedFrom column.id is unchanged and a receiver that deduplicates on id treats the replay as a duplicate rather than a second event. The new delivery gets its own X-Forge-Delivery, and attempts resets to 0.
403 permission_denied or forbidden
403 permission_denied or forbidden
permission_denied: missing webhooks:manage (named in error.requiredPermission). forbidden: the caller is not an External App, or the app no longer holds the scope required to receive this event. Replay re-checks the event’s subscription scope, exactly as live delivery does.404 resource_missing
404 resource_missing
No delivery with that id, or the delivery belongs to another External App. Both answer
404 deliberately: a 403 would confirm that another app’s delivery id exists.409 invalid_state
409 invalid_state
The delivery is still
pending (a retry may yet fire) or its subscription has been revoked. Neither can be replayed.Redeliver an event
webhooks:manage permission. Replays the newest delivery of an event to one of the calling app’s subscriptions, through the same checks and with the same answer as Replay a delivery.
The event to redeliver: the envelope
id the receiver saw, as GET /api/v3/events lists it.Which of the app’s subscriptions to redeliver to. Required when the event reached more than one of them that is not revoked.
400 bad_request
400 bad_request
eventId is missing, or the event reached more than one of the app’s subscriptions that are not revoked and subscriptionId names none.404 resource_missing
404 resource_missing
The event never reached any of the app’s subscriptions, or does not exist. Both answer alike.
409 invalid_state
409 invalid_state
The event’s newest delivery is still
pending, or its subscription has been revoked.List a delivery’s attempts
webhooks:read permission. Answers one of the calling app’s deliveries with its attempt log, newest last, at most ten entries.
One entry per attempt:
attempt, attemptedAt (Unix ms), outcome (delivered or failed), httpStatus (absent when no response came back), durationMs and, on a failure, error (at most 500 characters). Empty for a delivery sent before the log existed.The delivery’s state:
pending, delivered or failed. attempts and maxAttempts sit beside it, with eventId (null on a dispatch callback).404.
Delivery semantics
Forge delivers events with at-least-once semantics. The receiver must be idempotent — the same delivery may arrive more than once after a transient failure. Deduplicate on the envelope’sid, which webhook-id repeats: it is stable across retries and across a replay. X-Forge-Delivery identifies one delivery only.
Every delivery carries these headers:
There is no
X-Forge-Event-Id header — earlier revisions of this page listed one, but the platform has never emitted it. Use the envelope’s id, or X-Forge-Delivery for per-delivery identity.
A failed attempt is retried 9 more times over about 24 hours (gaps of 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, then 6h three times, each ±20%). After the tenth failure the delivery is failed and dead-lettered. Pausing, revoking or deleting the webhook stops its pending retries. The OpenAPI spec’s top-level webhooks section documents each event type’s body and these headers.
See Webhooks (operator guide) for verification snippets in Node and Python, the full retry schedule, and the auto-pause failure budget.
No ordering guarantee
Deliveries are scheduled and retried independently, so they arrive in no particular order, and the envelope carries no sequence counter to detect a hole with.orderingKey names the stream an event belongs to and occurredAt orders within it, but neither is a delivery promise.
Reconcile against GET /api/v3/events, whose insertion order is authoritative: store the cursor you last processed, page forward from it when you suspect a gap, and deduplicate on the envelope’s id.
Related
- Events — the canonical event log you reconcile against
- Approval lifecycle — the HITL events
- Workflow execution — the run-lifecycle events
- External Apps — the principals that own webhook subscriptions
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token - MCP server — the
webhookstool group

