Webhooks
Events
GET /api/v2/events — the cursor-paginated canonical event log an External App reconciles webhook delivery against. Opaque cursors, type filtering, the two-layer visibility rule, and the 30-day window.
GET
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
Webhooks notify; this endpoint is the source of truth. Deliveries are scheduled and retried independently and carry no sequence counter, so a receiver cannot tell from the delivery stream alone whether it missed something.GET /api/v2/events returns the same events out of the canonical log in insertion order behind an opaque cursor — which is what makes a gap detectable and recoverable.
id is the join key between the two surfaces.
Every webhook’s id is readable here within the 30-day window: Forge does not deliver an event it could not write to this log.
Authentication
External App credential. Requires theevents:read permission as the entry point — but holding it alone returns nothing. See Visibility below.
Query parameters
Opaque pagination token from a previous response’s
nextCursor. Omit to start at the beginning of the retention window.Treat the value as opaque: its encoding is not part of the contract and may change. Round-trip it verbatim — do not parse, truncate, or reconstruct it. A cursor advances past the last row of the page you received, so paging with the cursor you were handed neither repeats nor skips a row.Comma-separated event types to restrict the page to, e.g.
workflow.completed,step.completed. Omit for every event visible to the caller.Filtering narrows the result set only — it never widens visibility. An event you have no scope for stays invisible whether or not you name its type.Page size, 1 to
100. Defaults to 50. A value above 100 is 400 too_big; a non-integer is a 400.Response
Cursor for the next page, in
data.nextCursor (not meta), or null when the window is exhausted. A page is read first and filtered afterwards, so a short or empty page with a non-null cursor is normal: keep paging until the cursor is null. null means “you are caught up as of this read”, not “no more events will ever exist” — poll again later with the last non-null cursor you stored.There is deliberately no
sequence field on the envelope. A per-orderingKey counter would be a transactional write on the run or session row, putting every parallel branch of a workflow DAG into write contention for the same document. Ordering comes from paging this endpoint, not from a counter on the event.Visibility
Three conditions, all required. Failing any one of them means the event is simply absent from your pages — there is no error, and no way to tell it existed.1
Entry scope: the app holds events:read
Without it the request itself is a
403. This is the gate on the endpoint, not on any particular event.2
Per-event scope: the app's roles cover that event's subscriptionScope
Each event type declares the catalog permissions required to see it —
runs:read for workflow.* and step.*, audit:read, grants:read and policies:read for approval.*, and so on (the full map). An app with events:read and nothing else sees an empty log. "admin"-scoped events are operator-only and never appear here for any app, whatever scopes it holds.3
Initiator match: the app caused the event
An app sees only events it initiated. This is the same predicate the webhook fan-out uses — one shared function, so the push surface and the pull surface cannot drift into disagreeing about what an app is allowed to see.
Retention
The window is 30 days, matching webhook delivery retention. Events older than that are pruned and are not recoverable through this endpoint. An outage longer than the window is a data-loss event for your integration — alert on your reconciliation cursor falling behind long before it approaches 30 days.Worked example: recovering from an outage
Your receiver was down from 02:00 to 06:00. Some deliveries were retried into your endpoint and failed; some dead-lettered. Rather than replaying each delivery, page the log forward from the last cursor you committed.Your handler is a no-op when called twice with the same
event.id. That single property is what turns at-least-once delivery plus a cursor walk into an exactly-once integration.Errors
400 bad_request
400 bad_request
A non-integer
limit, or a malformed cursor. A cursor from a different deployment or a hand-edited one lands here rather than silently returning the wrong window.403 permission_denied or forbidden
403 permission_denied or forbidden
permission_denied: missing the events:read entry permission (named in error.requiredPermission). forbidden: the caller is not an External App. Note that an app with events:read but no per-event scopes gets 200 and an empty events array — not a 403.Related
- Webhooks (operator guide) — the scope map, the v2 envelope, and the reconciliation recipe in full
- Webhooks HTTP API — subscriptions, signing, and delivery replay
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token - MCP server —
forge_call_operationwith operationIdlistEvents
Authorizations
Query Parameters
Response
One page of the event log

