Skip to main content
POST
Register a webhook
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

POST /api/v2/webhooks Create a new webhook subscription owned by the calling External App. The response includes the signing secret — Forge will not re-emit it.

Authentication

External App credential. Requires permission webhooks:manage.

Request body

string
required
HTTPS endpoint Forge will POST to. HTTP URLs and URLs containing CR/LF are rejected.
string[]
required
Non-empty subset of supported event types — see Webhooks domain.
string
Human-readable label for the subscription (shown in the Forge Console).

Responses

string
Convex ID of the created subscription. Use it to delete or rotate the secret later.
string
HMAC signing secret. Forge will not re-emit it — capture it immediately and store in a secrets manager.
string
Reminder string emphasizing the secret will not be shown again. Render it to operators in your UI when surfacing the response.
This response is never stored for Idempotency-Key replay. A repeat under the same key and body answers 201 with only the webhook’s data.id (id-only replay, Idempotency-Replay-Disclosure: id-only), without the secret, and does not create a second webhook. If a create’s outcome is unknown, repeat it with the same key to learn the id, then rotate its secret.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Body

application/json
url
string
required

HTTPS endpoint to receive webhook deliveries

events
string[]
required

Event types to subscribe to; "*" is every event whose subscription scope the app holds. An event whose scope the app lacks answers 400.

Minimum array length: 1
label
string

Human-readable label

Response

Webhook created; the secret is shown once A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only data.id (IdOnlyReplay, Idempotency-Replay-Disclosure: id-only).

data
object
required
meta
object
required