> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Subscribe External Apps to scope-gated platform events and replay a past delivery. Each delivery is the v2 event envelope, signed with a timestamped HMAC (X-Forge-Signature-V2) and retried.

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](https://docs.gloo.com/forge/run/webhooks.md#the-v2-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.

| Permissions (all required) | Events it unlocks |
| - | - |
| `runs:read` | `workflow.started`, `workflow.completed`, `step.started`, `step.completed`, `step.skipped` |
| `audit:read`, `grants:read`, `policies:read` | `approval.requested`, `approval.resolved`, `approval.sla_breached`, `approval.reminder`, `human.assigned`, `governance.*` |
| `cost:read` | `budget.*`, `cost.anomaly` |
| `webhooks:read` | `event.delivery.failed` — an app hears about its own dying subscriptions |
| `skills:read` | `skill.review_verdict` |
| `chat:read` | `chat.session.completed` — `chat.message.created` is events-API-only and is **rejected** on subscribe with a message pointing at `GET /api/v3/events`, rather than accepted into a subscription that could never fire |
| `procedures:read` | `procedure.run.started`, `procedure.run.completed`, `procedure.run.failed` |
| `human_tasks:use` | `human_task.completed`, `human_task.canceled` — your own asks to people; see [Human task events](#human-task-events) |

`"*"` 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)](https://docs.gloo.com/forge/run/webhooks.md#event-types-and-subscription-scopes) for the full table.

## Human task events

An External App that [asks a person](https://docs.gloo.com/forge/reference/http-api/governance/requestHumanTask.md) 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:

```json theme={null}
{
  "type": "human_task.completed",
  "humanTaskId": "hir_456",
  "clientReference": "vendor-4711",
  "kind": "external_app_request",
  "state": "completed",
  "action": "approve",
  "occurredAt": 1792310400000,
  "initiator": { "kind": "externalApp", "id": "fca_..." }
}
```

`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](https://docs.gloo.com/forge/reference/http-api/governance/getRequestedHumanTask.md).

* **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](https://docs.gloo.com/forge/reference/idempotency.md#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](https://docs.gloo.com/forge/run/webhooks.md#rotating-the-secret).

> [!WARNING]
>
> 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

| Path | Method | Permission | Purpose |
| - | - | - | - |
| `POST /api/v3/webhooks` | POST | `webhooks:manage` | Create a subscription. Returns the secret once. |
| `GET /api/v3/webhooks` | GET | `webhooks:read` | List subscriptions, revoked ones included, up to 100 per page, continued with `meta.nextCursor`. An External App lists its own; a platform or Personal key lists every subscription. |
| `DELETE /api/v3/webhooks/{webhookId}` | DELETE | `webhooks:manage` | Revoke a subscription by `id`. |
| `POST /api/v3/webhooks/{webhookId}/revoke` | POST | `webhooks:manage` | Revoke a subscription with a platform or Personal key. An External App revokes with `DELETE`. |
| `PATCH /api/v3/webhooks/{webhookId}` | PATCH | `webhooks:manage` | Change a subscription's `url`, `events` or `label` (name at least one), under the checks create runs. A platform or Personal key may also set `authToken`, or clear it with `null`. The secret does not change. |
| `POST /api/v3/webhooks/{webhookId}/pause` | POST | `webhooks:manage` | Pause a subscription: it receives no new event while paused, and a delivery whose retry comes due while paused stops as `failed`. A test or a replay still takes its first attempt. |
| `POST /api/v3/webhooks/{webhookId}/resume` | POST | `webhooks:manage` | Resume a subscription, paused by hand or by the auto-pause, and clear its failure streak. Resume does not restart a delivery that stopped while paused; [replay](#replay-a-delivery) it. |
| `POST /api/v3/webhooks/{webhookId}/test` | POST | `webhooks:manage` | Queue one `webhook.test` delivery, signed and sent like any other, with a new envelope `id` each time. Answers `202` with its `deliveryId`. It never counts toward the auto-pause streak. |
| `GET /api/v3/webhooks/{webhookId}/deliveries` | GET | `webhooks:read` | List a subscription's deliveries by `subscriptionId`, newest first, a page at a time (`limit`, `cursor`). No payload is listed; a revoked subscription's deliveries still list. |
| `POST /api/v3/webhooks/{webhookId}/rotate-secret` | POST | `webhooks:manage` | Mint a new secret for an existing subscription. Returns the new secret once, and when the replaced one stops signing. |
| `POST /api/v3/webhook-deliveries/{deliveryId}/replay` | POST | `webhooks:manage` | Re-send one of the caller's own past deliveries. See [Replay](https://docs.gloo.com/forge/reference/http-api/webhooks/replay.md). |

## Replay a delivery

```
POST /api/v3/webhook-deliveries/{deliveryId}/replay
```

Requires the `webhooks:manage` permission. Ownership is enforced server-side off the authenticated principal.

**deliveryId** `string` *required*

The delivery to replay — the `X-Forge-Delivery` header value from the original request.

**deliveryId** `string`

Id of the **new** delivery row the replay created.

**replayedFrom** `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.

```bash cURL theme={null}
curl -X POST https://api.forge.gloo.com/v2/webhooks/deliveries/replay \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deliveryId": "wd_01J8..."}'
```

```ts TypeScript theme={null}
const { data } = await forge.replayWebhookDelivery("wd_01J8...");
console.log(data.deliveryId, data.replayedFrom);
```

> [accordion] 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.

> [accordion] 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.

> [accordion] 409 invalid\_state
>
> The delivery is still `pending` (a retry may yet fire) or its subscription has been revoked. Neither can be replayed.

> [!TIP]
>
> Replay is for a handful of known-bad deliveries. For a window-shaped outage, page [`GET /api/v3/events`](https://docs.gloo.com/forge/reference/http-api/events) instead — one cursor walk, and it also recovers events whose deliveries were never queued.

## Redeliver an event

```
POST /api/v3/webhook-deliveries/redeliver
```

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](#replay-a-delivery).

**eventId** `string` *required*

The event to redeliver: the envelope `id` the receiver saw, as [`GET /api/v3/events`](https://docs.gloo.com/forge/reference/http-api/events) lists it.

**subscriptionId** `string`

Which of the app's subscriptions to redeliver to. Required when the event reached more than one of them that is not revoked.

**deliveryId** `string`

Id of the **new** delivery row.

**replayedFrom** `string`

The delivery it replays: the event's newest delivery to that subscription.

> [accordion] 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.

> [accordion] 404 resource\_missing
>
> The event never reached any of the app's subscriptions, or does not exist. Both answer alike.

> [accordion] 409 invalid\_state
>
> The event's newest delivery is still `pending`, or its subscription has been revoked.

## List a delivery's attempts

```
GET /api/v3/webhook-deliveries/{deliveryId}/attempts
```

Requires the `webhooks:read` permission. Answers one of the calling app's deliveries with its attempt log, newest last, at most ten entries.

**attemptLog** `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.

**status** `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:

| Header | Value |
| - | - |
| `X-Forge-Event` | The event type (e.g. `approval.requested`). |
| `X-Forge-Delivery` | The delivery id. **Stable across all retry attempts** of the same delivery — it identifies the delivery, not the attempt. |
| `X-Forge-Signature-V2` | `t=<unix-ms>,v1=<hex>` — HMAC-SHA256 over `` `${t}.${body}` ``, keyed by the subscription secret. |
| `webhook-id` | [Standard Webhooks](https://www.standardwebhooks.com) message id: the envelope's event `id`, the dedupe key. |
| `webhook-timestamp` | Standard Webhooks timestamp: the attempt time in Unix seconds. |
| `webhook-signature` | `v1,<base64>` — HMAC-SHA256 over `` `${webhook-id}.${webhook-timestamp}.${body}` ``, keyed by the base64-decoded `whsec_` form of the secret (`whsec_` + base64 of its UTF-8 bytes). |

> [!WARNING]
>
> 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)](https://docs.gloo.com/forge/run/webhooks.md#retries-and-the-failure-budget) 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`](https://docs.gloo.com/forge/reference/http-api/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](https://docs.gloo.com/forge/reference/http-api/events.md) — the canonical event log you reconcile against
* [Approval lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle) — the HITL events
* [Workflow execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md) — the run-lifecycle events
* [External Apps](https://docs.gloo.com/forge/reference/http-api/externalApps) — the principals that own webhook subscriptions
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token
* [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) — the `webhooks` tool group


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.