Skip to main content
Forge can stream events to your systems as they happen. Approvals, workflow lifecycle transitions, and other governance signals are emitted as webhook deliveries to subscribed endpoints. This page covers what you can subscribe to, how delivery works, how to make receivers safe, and how to replay deliveries when a downstream consumer has been down. When to reach for something else: if you want to read Forge state on-demand (e.g., “list runs that completed in the last hour”), use the HTTP API. Webhooks are for push delivery — the platform calls you when something happens. If your consumer is fine with polling, the API is simpler.

Subscribing

A webhook subscription belongs to an External App. From the Forge Console’s Platform → Developers → External Apps page (see External Apps), open your app and add a subscription: On create, the platform returns the signing secret exactly once. The secret is stored AES-256-GCM-encrypted at rest. You will not see it again: no list or read returns it, in plaintext or encrypted — not the Console’s webhook lists, not GET /api/v3/webhooks, not the MCP tools. Copy it into your destination’s secret store at create time. The platform cannot recover it. The rotate-secret endpoint mints a new secret if you lose the old one. External-app subscriptions are initiator-scoped: an app only receives events it initiated. Admin-owned subscriptions (without an externalApplicationId) receive every matching event in the workspace, including operator-only events.

Event types and subscription scopes

Every event definition in the platform declares a subscriptionScope — the catalog permissions an External App must all hold to subscribe to it, or "admin". This replaced the old fixed five-event allowlist: an app that holds runs:read can now subscribe to step.completed, and an app that holds nothing beyond inference scopes can subscribe to nothing at all. The scope is checked in two places:
  • At subscribe time. Naming an event whose scope the app lacks returns 400 naming the missing permissions.
  • At dispatch time, per delivery. Revoking a scope narrows delivery immediately — a subscription created while a scope was held stops delivering the moment the scope goes away, without anyone editing the subscription. Revocation is a patch, not a request.
"admin" is the sentinel for operator-only events. An admin-scoped event is never app-subscribable and never appears in the app-facing events API, no matter which scopes the app holds. Admin-owned subscriptions (those with no owning External App) receive admin events and bypass the scope gate.

The scope map

Every event Forge publishes carries a subscription scope. The chat.* events are published only for sessions an External App created — a human’s internal conversation is never an app’s event. chat.message.created is events-API-only (no webhook channel — message-rate delivery is a volume hazard on the hottest write path), so it is readable through GET /api/v3/events but cannot be subscribed to.

Governance events name their decision

governance.denied, governance.sensitive_data and governance.run_cost_cap_exceeded carry data.decisionId: the id of the Trust Fabric decision recorded for the dispatch. Read it with Get a recorded decision to join the event to the decision. Forge records the decision before it emits governance.denied or governance.sensitive_data, so no event names a decision that was not recorded. governance.run_cost_cap_exceeded leaves decisionId out when the block’s decision could not be recorded; the run is blocked either way. A subscription declares the exact event names it wants. The string * means “every event whose scope I currently hold” and is resolved at dispatch, so granting a new scope widens a * subscription without editing it. Other wildcard / hierarchical patterns are not supported. External-app subscriptions remain initiator-scoped on top of the scope gate: an app receives an event only if it both holds the scope and initiated the event. Both conditions, always.

Human task events are ids only

An External App or a platform API key holding human_tasks:use can ask named people for a decision or input. To let an app ask, give it a role with human_tasks:use; the app’s token must also name human_tasks:use in its scope. No preset includes it. human_task.completed and human_task.canceled tell the app that asked what happened, with ids only: the task id, the app’s clientReference, the state, the app’s own action id or the cancelReason, and the app as initiator. They never carry the answer, a reason, or who answered; the app reads those with GET /api/v3/governance-requested-human-task-lookup.
  • Your admin subscriptions see every app’s asks. An admin subscription (no owning app), a * one included, receives these events for every app: task ids, client references and action ids. That is intended operator visibility; nothing personal is in the payload.
  • A platform API key has no webhook of its own. Its asks’ events reach admin subscriptions only; the key polls getRequestedHumanTask.
  • No event on supersede. Deactivating or deleting an app, revoking or expiring a key, or removing the grant that covers an ask closes its open asks as superseded, with no webhook.
  • A sub-unit grant asks but does not hear. Delivery re-checks the app’s scopes at the unit its requests resolve to, the deployment root. An app whose human_tasks:use covers only a sub-unit can ask people homed there, but its subscription to these events is refused and nothing is delivered; it polls getRequestedHumanTask, which works while its grant covers the task’s home.

Delivery shape

Each delivery is one HTTP POST whose JSON body is the v2 envelope. There is one body shape; nothing about the subscription changes it.

The v2 envelope

There is deliberately no sequence field. A per-orderingKey counter would have to be a transactional write on the run or session row, which would put every parallel branch of a workflow DAG into write contention for the same document. Ordering is recovered by paging the events API, not by trusting a counter on the delivery.
Earlier subscriptions could be created with a raw-payload body (payloadVersion: "v1") or with a Splunk-HEC wrapper (format: "splunk_hec"). Both delivery modes have been removed. Every subscription — including admin-owned ones — now receives the envelope above, and no request carries an Authorization: Splunk … header. A receiver that read the old top-level payload reads data instead; a Splunk collector is fed by an intermediary that re-wraps the envelope.

Signing

Every delivery carries a timestamped HMAC-SHA256 signature keyed by the subscription’s secret. Verify it before trusting the payload:
v1 is the HMAC over t + "." + body — the timestamp is inside the signed message, so an attacker who captures a delivery cannot refresh t to slip past your window without the secret. Replay protection is your side of the contract: reject deliveries whose t is more than 5 minutes from now, in either direction. Without that check the timestamp buys you nothing. Verify either X-Forge-Signature-V2 or the Standard Webhooks signature; both sign every attempt. 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. Do not read it. Verify over the bytes you received, not a re-serialization of the parsed JSON: a JSON.parse → JSON.stringify round trip can reorder keys or reformat numbers and will break verification.

Standard Webhooks

Every delivery also carries the three Standard Webhooks headers, so a receiver can verify it with any Standard Webhooks library instead of the code above: A Standard Webhooks library takes its secret as whsec_<base64 key>. For a Forge secret, that is whsec_ followed by the base64 of the secret’s UTF-8 bytes, so both signatures are keyed by the same bytes. A secret already in whsec_ form is used as it is.
Node.js

Rotating the secret

POST /api/v3/webhooks/{webhookId}/rotate-secret returns a new secret once, with previousSecretExpiresAt. Until then (at least 24 hours), webhook-signature carries two signatures, v1,<new> v1,<old>, so a receiver still holding the old secret keeps verifying while it switches. A Standard Webhooks library accepts a header with several signatures. X-Forge-Signature-V2 carries only the new secret’s signature from the moment of rotation: a receiver that verifies only it must switch at once. A second rotation inside the window replaces the old secret, so at most two secrets are ever live. Past previousSecretExpiresAt the old secret never signs again, and Forge deletes it. To retire a leaked secret at once, revoke the subscription and create a new one: a rotation leaves the old secret valid for the window.

Delivery headers

There is no X-Forge-Event-Id header. An earlier revision of the API reference listed one; the platform has never emitted it.

Retries and the failure budget

A delivery that returns a non-2xx status, takes longer than 10 seconds, or answers with a redirect has failed that attempt. Forge retries it on a fixed schedule that spans about a day. Every delivery gets 10 attempts, with these gaps between them: Each gap is spread by up to ±20% at random. When many deliveries fail together because one receiver is down, the jitter keeps their retries from arriving as one burst when it recovers. Without jitter, the tenth attempt lands 24 hours 4 minutes after the first. The short early gaps cover a receiver that blips during a deploy. The 6-hour cap means a receiver that comes back after an overnight outage is not left waiting most of a day for the next try. Every attempt carries the same X-Forge-Delivery id and the same body. Only the X-Forge-Signature-V2 timestamp changes. The delivery’s attempts count rises on each attempt. List a delivery’s attempts to read it with maxAttempts and an attemptLog entry for each attempt, carrying its time, outcome, httpStatus and error. The OpenAPI spec’s webhooks section documents every event’s body and headers. The final state is failed. After the tenth failed attempt, the delivery’s status is failed, attempts is 10, and lastError and httpStatus hold the last failure. It is dead-lettered as described below and can be replayed. Disabling a webhook stops its retries. When a subscription is paused, revoked or deleted, its next scheduled retry sends nothing and schedules nothing. The delivery moves to failed with lastError set to Retries stopped: webhook paused (or revoked or deleted). These rows are not dead-lettered and do not count toward the failure budget: the receiver did not fail, the webhook was turned off. After you resume a paused webhook, replay the deliveries you still want. A paused webhook still takes a first attempt that an operator asks for, such as a test delivery or a replay, but it gets no automatic retries. Losing access stops retries too. Before each retry to an app-owned webhook, Forge re-checks the rule it applied at dispatch. The app must be active, its current role grants must still cover the event, and it must have initiated the event. Revoking a role leaves the subscription active, so without this check a queued event could reach an app hours after it lost access. A delivery that no longer qualifies ends failed with lastError set to Retries stopped: webhook owner no longer holds access to this event, and is neither dead-lettered nor counted toward the failure budget. Each subscription tracks consecutiveFailures. A successful delivery resets it to 0. After 10 consecutive final failures the subscription auto-pauses and no new deliveries are queued until an operator resumes it (resuming also resets the counter). This is what keeps a dead downstream from accumulating an unbounded backlog. Because each delivery retries for about a day, a dead endpoint reaches its tenth final failure, and auto-pauses, roughly a day after it stops answering. Two things happen when retries are exhausted:
  • The delivery is dead-lettered. A dead-letter record is written with the delivery id, the last error, and the attempt count. The failed delivery itself is retained indefinitely (retention prunes only deliveries that succeeded), so the payload stays available for forensics.
  • The auto-pause is announced. Crossing the threshold emits event.delivery.failed on the notification bus — operator bell, plus any admin subscription that carries that event. One alert per pause, not one per failure.

Retention

A daily job deletes delivered deliveries older than 30 days. failed rows (the forensic record behind each dead-letter entry) and pending rows (a retry may still be scheduled) are never pruned. The canonical event log shares the same 30-day window.

Ordering, gaps, and reconciliation

Forge does not deliver webhooks in order. This is a contract, not an implementation detail:
  • Each delivery is scheduled and retried independently. A delivery that fails once and succeeds on its second attempt arrives after events that were emitted later.
  • Parallel branches of a workflow DAG emit concurrently. There is no total order to deliver them in.
  • The envelope carries orderingKey so you can tell which stream an event belongs to, and occurredAt so you can sort within it — but neither is a delivery guarantee, and the envelope carries no sequence counter you could use to detect a hole.
What is authoritative is the canonical event log: GET /api/v3/events returns events in insertion order behind an opaque cursor. Deliveries reference the same event ids, so the two surfaces are joinable. An event Forge could not write to the log after three attempts is not delivered at all, and operators see a notification.event_log_write_failed audit event for it.

Reconciliation recipe

1

Treat the webhook as a nudge, not the payload

Handle the delivery if you can, but record the envelope’s id as processed. Never treat “no delivery arrived” as “nothing happened”.
2

Persist your cursor

Every time you finish a page of GET /api/v3/events, store the returned nextCursor atomically with whatever the page’s events caused you to do. The cursor is your recovery point.
3

On a suspected gap, page forward from the last stored cursor

Your receiver was down, or a delivery dead-lettered, or a scope was briefly revoked. Page GET /api/v3/events?cursor=<last> until nextCursor is null.
4

Deduplicate on the event id, not the delivery

An event can reach you twice by two different routes — once as a webhook, once from the log — and two events sharing a millisecond may straddle a page boundary. The envelope id is stable across every route and every replay, and webhook-id carries the same value. X-Forge-Delivery names one delivery, and a replay is a new delivery.
Your handler is a no-op when called twice with the same event.id.
The log window is 30 days. An outage longer than that is not recoverable through this endpoint — events older than the window are pruned. Alert on your reconciliation cursor falling behind long before it approaches 30 days.

Replay

When a downstream consumer has been down for a window and you want to re-send the events that landed during the outage, the Replay affordance queues a new delivery that carries the original payload byte-for-byte. A replay answers { deliveryId, replayedFrom }: deliveryId is the new delivery’s id (its X-Forge-Delivery value), and replayedFrom is the id of the delivery it re-sends. Because the payload is copied verbatim, the envelope’s id survives the replay while X-Forge-Delivery does not — the replay is a distinct delivery of the same event. Receivers that key on the envelope id, or on webhook-id (the same value), see the replay as a duplicate and ignore it (no double-action). Receivers that key on X-Forge-Delivery, or that do not deduplicate at all, see it as a new event. Build dedup on the receiver side, on id. It is the cheap operation that converts an unreliable network into an exactly-once integration. On the replayed delivery:
  • replayedFrom names the original delivery’s id.
  • eventId is carried forward, so the delivered envelope’s id is unchanged.
  • attempts starts again at 0, because the replay is a fresh delivery.

App-side replay

An External App can replay its own deliveries without an operator, at parity with the console affordance:
Requires webhooks:manage. Ownership is enforced server-side off the authenticated principal — another app’s delivery answers 404, the same as an unknown one, so the endpoint cannot confirm that an id exists. The SDK exposes it as replayWebhookDelivery(deliveryId) and the MCP server through forge_call_operation with operationId replayWebhookDelivery.

Redeliver by event id

A receiver usually knows the event it missed, not the delivery. Redeliver it by the envelope id:
Forge finds the newest delivery of that event to one of your subscriptions and replays it, exactly as POST /api/v3/webhook-deliveries/{deliveryId}/replay would; the answer is the same { deliveryId, replayedFrom }. When the event reached more than one of your subscriptions that are not revoked, name one with subscriptionId; without it the request answers 400. An event your app never received answers 404. Requires webhooks:manage.

Attempt log

Each delivery keeps its attempts, newest last, at most ten:
Each entry has the attempt number, when it was sent (attemptedAt, Unix ms), outcome (delivered or failed), the receiver’s httpStatus (absent when no response came back: a timeout, a DNS failure or a redirect), durationMs and, on a failure, error. A delivery sent before the log existed answers an empty attemptLog. Requires webhooks:read; another app’s delivery answers 404.
Replay is the right tool for a handful of known-bad deliveries. For a window-shaped outage — “we were down from 02:00 to 06:00” — page the events API instead: it is one cursor walk rather than N replays, and it catches events whose deliveries were never queued (a revoked scope, a paused subscription) as well as ones that failed.

Test delivery

From the subscription’s row in the Forge Console, Send test posts a synthetic webhook.test payload to your endpoint using the subscription’s secret + format. It is available on both the admin Platform → Developers → Webhooks page and the per-app Webhooks tab under Platform → Developers → External Apps. An External App sends the same test to one of its own subscriptions with POST /api/v3/webhooks/{webhookId}/test (webhooks:manage). Each test is a new event with its own envelope id. A test delivery never counts toward the auto-pause streak: a failed test does not add to consecutiveFailures, and a delivered one does not clear it. Use Resume (or POST /api/v3/webhooks/{webhookId}/resume) to clear the streak.

Operating subscriptions

  • Name the events you consume. A * subscription widens whenever the app gains a scope, so it accumulates event types you never handle. List the events you act on.
  • Verify every delivery. A receiver that skips the X-Forge-Signature-V2 check, or its five-minute timestamp window, can be spoofed by anyone who knows the URL.
  • Treat a repeated auto-pause as an incident in the receiver. If a subscription keeps reaching the ten-failure auto-pause, the downstream is unhealthy. Involve the team that owns it before you resume, then replay or reconcile the gap.
  • Read the deliveries panel. Each subscription’s row in the Console expands to its deliveries, with status, HTTP response code and timing. A replayed delivery carries a replay badge.

When to subscribe vs. poll

This is not really a fork. A production integration runs both: webhooks for latency, the events API as the reconciliation floor underneath them. The polling path is what makes the push path safe to lose.