> ## 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 to Forge events: scope-gated events, the v2 delivery envelope, X-Forge-Signature-V2 verification, the 24-hour retry schedule, ordering and reconciliation, replay, and retention.

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.

Webhooks **notify**. The [canonical event log](https://docs.gloo.com/forge/reference/http-api/events.md) is the **source of truth**. Deliveries are independently scheduled and retried, so they arrive without an ordering guarantee — reconcile against `GET /api/v3/events`. See [Ordering, gaps, and reconciliation](#ordering-gaps-and-reconciliation).

**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](https://docs.gloo.com/forge/reference/http-api/runs). 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](https://docs.gloo.com/forge/console/platform/external-apps)), open your app and add a subscription:

| Field | What goes here |
| - | - |
| URL | An HTTPS endpoint on a routable public host. Rejected at create **and update** time: non-HTTPS schemes, CR/LF, embedded credentials (`https://user:pass@...`), and loopback / link-local / private / cloud-metadata hosts (`localhost`, `127/8`, `10/8`, `172.16/12`, `192.168/16`, `169.254/16`, `::1`, `fc00::/7`, `fe80::/10`). |
| Events | A non-empty array of event-type strings. Each must be an event whose [subscription scope](#event-types-and-subscription-scopes) the app holds; `*` means "every event whose scope I hold". |
| Label | Optional human-readable name. |

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

| Events | Scope (all required) |
| - | - |
| `workflow.started` / `workflow.completed`, `step.*` | `runs:read` |
| `approval.*`, `human.assigned`, `governance.*` | `audit:read`, `grants:read`, `policies:read` |
| `budget.*`, `cost.anomaly` | `cost:read` |
| `event.delivery.failed` | `webhooks:read` — an app hears about its own dying subscriptions |
| `chat.session.completed`, `chat.message.created` | `chat:read` |
| `procedure.run.*` | `procedures:read` |
| `skill.review_verdict` | `skills:read` |
| `human_task.completed`, `human_task.canceled` | `human_tasks:use` |
| `alert.*`, `observability.*`, `runtime.*`, `model.deprecation.*`, `lifecycle.*`, `synthesis.*`, `builder.*`, `secret.rotation_stale` | `"admin"` — operator-only |

> [!NOTE]
>
> 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](https://docs.gloo.com/forge/reference/http-api/governance/getEvidence.md) 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](https://docs.gloo.com/forge/reference/http-api/governance/requestHumanTask.md) 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

```json theme={null}
{
  "id": "evt_...",
  "type": "workflow.completed",
  "apiVersion": "2026-08-01",
  "occurredAt": 1785500000000,
  "orderingKey": "run_<id>",
  "initiator": { "kind": "externalApp", "id": "fca_..." },
  "data": { }
}
```

| Field | Meaning |
| - | - |
| `id` | The canonical event id — the row in the event log this delivery came from. Forge sends a webhook only after its event is in the log. **This is the dedupe key** that lets a delivery and an events-API row be recognised as the same event. An operator-only (`admin`) event is never in the log; its `id` is the same for every subscription. |
| `type` | The event type, same value as the `X-Forge-Event` header. |
| `apiVersion` | Envelope version. Bumped when the envelope shape changes; treat an unrecognised value as "stop parsing" rather than "parse optimistically". |
| `occurredAt` | Unix epoch milliseconds. |
| `orderingKey` | The natural stream this event belongs to — `run_<runId>` for run-scoped events. `null` when there is no natural stream. |
| `initiator` | `{ kind: "externalApp" \| "user" \| "system", id }`, or `null` when attribution could not be resolved. |
| `data` | The event payload itself. Everything outside `data` is identity and attribution. |

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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:

```
X-Forge-Signature-V2: t=<unix-ms>,v1=<hex-sha256-hmac>
```

`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](#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.

```js Node.js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_MS = 5 * 60 * 1000;

// `rawBody` must be the exact request body bytes as a string — not a
// re-serialized object.
export function verifyForgeWebhook(rawBody, header, secret, nowMs = Date.now()) {
  const parts = Object.fromEntries(
    String(header ?? "")
      .split(",")
      .map((kv) => kv.split("=").map((piece) => piece.trim())),
  );
  if (!/^\d+$/.test(parts.t ?? "") || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(nowMs - Number(parts.t)) > TOLERANCE_MS) return false;

  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, "hex");
  return expected.length === received.length && timingSafeEqual(expected, received);
}
```

```python Python theme={null}
import hashlib
import hmac
import re
import time

TOLERANCE_MS = 5 * 60 * 1000


# `raw_body` must be the exact request bytes, not a re-serialized dict.
def verify_forge_webhook(raw_body: bytes, header: str, secret: str, now_ms: int = 0) -> bool:
    now_ms = now_ms or int(time.time() * 1000)
    parts = dict(kv.strip().split("=", 1) for kv in (header or "").split(",") if "=" in kv)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"\d+", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(now_ms - int(t)) > TOLERANCE_MS:
        return False

    expected = hmac.new(
        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, v1)
```

#### Standard Webhooks

Every delivery also carries the three [Standard Webhooks](https://www.standardwebhooks.com) headers, so a receiver can verify it with any Standard Webhooks library instead of the code above:

| Header | Value |
| - | - |
| `webhook-id` | The envelope's event `id`. The same on every retry and on a replay of the event. |
| `webhook-timestamp` | The attempt time in Unix **seconds**. |
| `webhook-signature` | `v1,<base64>`: HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<raw body>`. After a rotation, two space-separated signatures; see [Rotating the secret](#rotating-the-secret). |

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.

```js Node.js theme={null}
import { Webhook } from "standardwebhooks";

const key = secret.startsWith("whsec_")
  ? secret
  : `whsec_${Buffer.from(secret, "utf8").toString("base64")}`;
const wh = new Webhook(key);
// Throws when the signature or the 5-minute timestamp tolerance fails.
const event = wh.verify(rawBody, request.headers);
```

### 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

| Header | Value |
| - | - |
| `X-Forge-Event` | The event type (e.g. `approval.requested`). |
| `X-Forge-Delivery` | The delivery id. Stable across every retry attempt of the same delivery; a replay is a new delivery with a new id. Use it to look up a delivery's attempts or to replay it, not to deduplicate. |
| `X-Forge-Signature-V2` | `t=<unix-ms>,v1=<hex>`. Re-signed per attempt with a fresh `t`, so a retry is never rejected by your tolerance window. |
| `webhook-id` | Standard Webhooks message id: the envelope's event `id`. **Deduplicate on this**, or on the body's `id`: they are the same value. |
| `webhook-timestamp` | Standard Webhooks timestamp: the attempt time in Unix seconds. |
| `webhook-signature` | Standard Webhooks signature, `v1,<base64>`, or two space-separated after a rotation; see [Standard Webhooks](#standard-webhooks). |

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:

| After attempt | Next attempt in |
| - | - |
| 1 | 1 minute |
| 2 | 3 minutes |
| 3 | 9 minutes |
| 4 | 27 minutes |
| 5 | 1 hour 21 minutes |
| 6 | 4 hours 3 minutes |
| 7, 8, 9 | 6 hours each |

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](https://docs.gloo.com/forge/reference/http-api/webhooks/listDeliveryAttempts.md) to read it with `maxAttempts` and an `attemptLog` entry for each attempt, carrying its time, outcome, `httpStatus` and `error`. The [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json)'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](#replay).

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

```ts theme={null}
let cursor = await store.getCursor();
for (;;) {
  const { data } = await forge.listEvents({ cursor, limit: 200 });
  for (const event of data.events) {
    if (await store.alreadySeen(event.id)) continue;   // the webhook already delivered it
    await handle(event);
    await store.markSeen(event.id);
  }
  if (data.nextCursor == null) break;
  cursor = data.nextCursor;
  await store.putCursor(cursor);
}
```

**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.
\[!TIP] Your handler is a no-op when called twice with the same `event.id`.

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

```
POST /api/v3/webhook-deliveries/<X-Forge-Delivery value>/replay
```

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

```
POST /api/v3/webhook-deliveries/redeliver
{ "eventId": "<envelope id>", "subscriptionId": "<optional>" }
```

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:

```
GET /api/v3/webhook-deliveries/<X-Forge-Delivery value>/attempts
```

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

> [!TIP]
>
> 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](https://docs.gloo.com/forge/reference/http-api/events.md) 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

| Pick webhooks when | Pick the events API when |
| - | - |
| You need millisecond-fresh notification (the on-call pager). | You can tolerate a poll interval. |
| Your downstream is always-on and accepts inbound HTTPS. | Your downstream is behind NAT or runs intermittently. |
| The event you want has a webhook channel. | The event is events-API-only (e.g. `chat.message.created`). |
| You want push. | You want ordering, gap recovery, or a backfill after an outage. |

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.

***

## Related

* [HTTP API — Events](https://docs.gloo.com/forge/reference/http-api/events.md)
* [HTTP API — Webhooks](https://docs.gloo.com/forge/reference/http-api/webhooks)
* [External Apps](https://docs.gloo.com/forge/console/platform/external-apps)
* [Audit](https://docs.gloo.com/forge/run/audit.md)
* [Observability alerts](https://docs.gloo.com/forge/run/observability.md#alerts)


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