Skip to main content
Webhook subscriptions let an External App receive event callbacks instead of polling the platform. Each subscription owns a 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 a subscriptionScope — 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 initiator is 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 superseded and 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:use covers only a sub-unit can ask people there but hears no webhook; it polls getRequestedHumanTask, which works there.

Secret handling

The secret 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.
Each External App is capped at a maximum number of webhook subscriptions. Create attempts beyond the cap return 409 conflict with the cap stated in the message.

Operations

Replay a delivery

Requires the webhooks:manage permission. Ownership is enforced server-side off the authenticated principal.
string
required
The delivery to replay — the X-Forge-Delivery header value from the original request.
string
Id of the new delivery row the replay created.
string
The original delivery this replay was created from, mirrored onto the new row’s replayedFrom column.
The replay reuses the original payload byte-for-byte, so the envelope’s 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.
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.
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.
The delivery is still pending (a retry may yet fire) or its subscription has been revoked. Neither can be replayed.
Replay is for a handful of known-bad deliveries. For a window-shaped outage, page GET /api/v3/events instead — one cursor walk, and it also recovers events whose deliveries were never queued.

Redeliver an event

Requires the 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.
string
required
The event to redeliver: the envelope id the receiver saw, as GET /api/v3/events lists it.
string
Which of the app’s subscriptions to redeliver to. Required when the event reached more than one of them that is not revoked.
string
Id of the new delivery row.
string
The delivery it replays: the event’s newest delivery to that subscription.
eventId is missing, or the event reached more than one of the app’s subscriptions that are not revoked and subscriptionId names none.
The event never reached any of the app’s subscriptions, or does not exist. Both answer alike.
The event’s newest delivery is still pending, or its subscription has been revoked.

List a delivery’s attempts

Requires the webhooks:read permission. Answers one of the calling app’s deliveries with its attempt log, newest last, at most ten entries.
object[]
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.
string
The delivery’s state: pending, delivered or failed. attempts and maxAttempts sit beside it, with eventId (null on a dispatch callback).
Another app’s or an unknown delivery answers 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’s id, 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:
Enforce the timestamp window when you verify X-Forge-Signature-V2: reject a delivery whose t is more than five minutes from now. A body-only X-Forge-Signature: sha256=<hex> header was emitted alongside V2 until the legacy path was removed — it carried no timestamp and was replayable indefinitely. Stop reading it.
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.