Webhook endpoints

GET /v1/webhooks

List Webhooks

Responses

• 200 array of WebhookOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks

Create Webhook

Request body (application/json, required)

Responses

• 201 WebhookCreated (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

PATCH /v1/webhooks/{webhook_id}

Patch Webhook

D58(a): edit url/events, and re-enable (`active: true`). D139(b)/(c): re-enabling clears the auto-disable markers and makes every delivery waiting on the endpoint due at once.

Path

• webhook_id string (uuid)

Request body (application/json, required)

Responses

• 200 WebhookOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

DELETE /v1/webhooks/{webhook_id}

Delete Webhook

Path

• webhook_id string (uuid)

Responses

• 204 no body: Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

GET /v1/webhooks/{webhook_id}/deliveries

List Deliveries

Path

• webhook_id string (uuid)

Query

• status string | null
• limit integer (>= 1, <= 200) default 50

Responses

• 200 array of DeliveryOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}

Get Delivery

D139(d): one delivery with the payload as posted and every attempt (the dashboard's viewer reads the same dict).

Path

• webhook_id string (uuid)
• delivery_id integer (>= -9223372036854776000, <= 9223372036854776000)

Responses

• 200 DeliveryDetailOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver

Redeliver

Path

• webhook_id string (uuid)
• delivery_id integer (>= -9223372036854776000, <= 9223372036854776000)

Responses

• 202 RedeliverOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks/{webhook_id}/deliveries/replay

Replay Deliveries

D139(e): queue again every dead (or dead and delivered) delivery created in [since, until), oldest first, at most REPLAY_LIMIT. Each goes out with attempt reset and a fresh signature; consumers dedupe on the event id as they do for a single redeliver. D140(k): audited, with the window and the count, whoever asked (an API key, or the dashboard user acting as one).

Path

• webhook_id string (uuid)

Request body (application/json, required)

Responses

• 202 ReplayOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks/{webhook_id}/disable

Disable Webhook

Path

• webhook_id string (uuid)

Responses

• 204 no body: Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks/{webhook_id}/ping

Ping Webhook

D58(a): queue one delivery of type `ping`, signed like any other. `ping` is not subscribable (EVENT_TYPES is unchanged); the deliverer sends every queued row regardless of the endpoint's event filter.

Path

• webhook_id string (uuid)

Responses

• 202 PingOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/webhooks/{webhook_id}/rotate-secret

Rotate Secret

D58(a): a new secret, shown once; the previous one keeps co-signing deliveries for ROTATION_GRACE (`v1=<new>,v1=<old>` in the header) so a handler can be switched without a signature outage. A second rotation inside the window retires the older secret immediately: at most two secrets are ever live.

Path

• webhook_id string (uuid)

Responses

• 200 WebhookCreated (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.