integrations
Tenant-scoped outbound webhook endpoints, deliveries, and replay.
| Method | Path | Operation ID |
|---|---|---|
| GET | /v1/webhook-endpoints |
listWebhookEndpoints |
| POST | /v1/webhook-endpoints |
createWebhookEndpoint |
| GET | /v1/webhook-endpoints/deliveries/{delivery_id} |
getWebhookDelivery |
| GET | /v1/webhook-endpoints/deliveries/{delivery_id}/attempts |
listWebhookDeliveryAttempts |
| POST | /v1/webhook-endpoints/deliveries/{delivery_id}/replay |
replayWebhookDelivery |
| GET | /v1/webhook-endpoints/event-catalog |
getWebhookEventCatalog |
| GET | /v1/webhook-endpoints/{endpoint_id} |
getWebhookEndpoint |
| DELETE | /v1/webhook-endpoints/{endpoint_id} |
deleteWebhookEndpoint |
| PATCH | /v1/webhook-endpoints/{endpoint_id} |
updateWebhookEndpoint |
| GET | /v1/webhook-endpoints/{endpoint_id}/deliveries |
listWebhookDeliveries |
| POST | /v1/webhook-endpoints/{endpoint_id}/disable |
disableWebhookEndpoint |
| POST | /v1/webhook-endpoints/{endpoint_id}/enable |
enableWebhookEndpoint |
| POST | /v1/webhook-endpoints/{endpoint_id}/rotate-secret |
rotateWebhookEndpointSecret |
| POST | /v1/webhook-endpoints/{endpoint_id}/secret-overlap/complete |
completeWebhookEndpointSecretOverlap |
| POST | /v1/webhook-endpoints/{endpoint_id}/test |
sendWebhookTestEvent |
GET /v1/webhook-endpoints
Section titled “GET /v1/webhook-endpoints”Operation ID: listWebhookEndpoints
List bounded tenant-owned outbound webhook endpoints.
List endpoints newest first. Deleted endpoints are excluded by default so the inventory is the set that can still act; include_deleted turns it into the retained history view.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit |
query | integer | no | Minimum 1. Maximum 100. Default 50. |
cursor |
query | string or null | no | |
include_deleted |
query | boolean | no | Default false. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookEndpointPageResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The page limit is outside its bound, or the cursor is unusable here: tampered, expired, issued for another tenant, or issued for a different collection or filter set. Every one of those fails closed with the same stable body. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
data |
array of WebhookEndpointResponse | yes | |
next_cursor |
string or null | no |
POST /v1/webhook-endpoints
Section titled “POST /v1/webhook-endpoints”Operation ID: createWebhookEndpoint
Create a policy-approved endpoint and issue its write-only signing secret.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Request body
Section titled “Request body”application/json: CreateWebhookEndpointRequest (required)
| Field | Type | Required | Description |
|---|---|---|---|
auto_disable_after_failures |
integer | no | Minimum 1. Maximum 100. Default 20. |
event_catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventType | yes | |
max_concurrency |
integer | no | Minimum 1. Maximum 20. Default 2. |
rate_limit_per_minute |
integer | no | Minimum 1. Maximum 600. Default 60. |
url |
string | yes | Max length 2048. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json IssuedWebhookEndpointResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Authentication conflict, endpoint limit, Idempotency-Key conflict, or a completed logical command whose one-time secret cannot be replayed. For secret_not_replayable, issue rotate-secret with a new Idempotency-Key. | application/json HttpErrorResponse or SecretNotReplayableResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
201 response fields
Section titled “201 response fields”| Field | Type | Required | Description |
|---|---|---|---|
endpoint |
WebhookEndpointResponse | yes | One endpoint, including the reviewed reason it stopped delivering. deleted is a readable state, not an absence: a deleted endpoint keeps serving its configuration and evidence to the owning tenant for the retention period, and refuses every mutation. |
secret |
string | yes |
GET /v1/webhook-endpoints/deliveries/{delivery_id}
Section titled “GET /v1/webhook-endpoints/deliveries/{delivery_id}”Operation ID: getWebhookDelivery
Read one tenant-owned delivery’s state and response evidence.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
delivery_id |
path | string | yes | Pattern: ^whd_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookDeliveryResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
attempt_count |
integer | yes | |
created_at |
string | yes | |
delivery_id |
string | yes | |
event_id |
string | yes | |
event_type |
CustomerEventType or const “webhook.test” | yes | |
next_attempt_at |
string or null | yes | |
replay_count |
integer | yes | |
response_body_sha256 |
string or null | yes | |
response_code |
integer or null | yes | |
status |
enum | yes | One of: pending, delivering, delivered, failed, dead. |
terminal_reason |
WebhookDeliveryTerminalReason or null | yes |
GET /v1/webhook-endpoints/deliveries/{delivery_id}/attempts
Section titled “GET /v1/webhook-endpoints/deliveries/{delivery_id}/attempts”Operation ID: listWebhookDeliveryAttempts
List bounded append-only attempt evidence for one delivery.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
delivery_id |
path | string | yes | Pattern: ^whd_[a-z2-7]{16}$. |
limit |
query | integer | no | Minimum 1. Maximum 100. Default 50. |
cursor |
query | string or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookAttemptPageResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The page limit is outside its bound, or the cursor is unusable here: tampered, expired, issued for another tenant, or issued for a different collection or filter set. Every one of those fails closed with the same stable body. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
data |
array of WebhookAttemptResponse | yes | |
next_cursor |
string or null | no |
POST /v1/webhook-endpoints/deliveries/{delivery_id}/replay
Section titled “POST /v1/webhook-endpoints/deliveries/{delivery_id}/replay”Operation ID: replayWebhookDelivery
Authorize delivery of the original immutable customer event again.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
delivery_id |
path | string | yes | Pattern: ^whd_[a-z2-7]{16}$. |
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json ReplayWebhookDeliveryResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Idempotency-Key was reused for a different delivery replay, or the matching logical replay is still in progress. Authentication provisioning may also conflict. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
event_id |
string | yes |
GET /v1/webhook-endpoints/event-catalog
Section titled “GET /v1/webhook-endpoints/event-catalog”Operation ID: getWebhookEventCatalog
Discover the exact versioned events an endpoint may subscribe to.
Discover the exact events an endpoint may subscribe to.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json CustomerEventCatalogResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | A verified email is unavailable for account provisioning. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventDescriptorResponse | yes | |
wildcard_supported |
const false | no | Default false. |
GET /v1/webhook-endpoints/{endpoint_id}
Section titled “GET /v1/webhook-endpoints/{endpoint_id}”Operation ID: getWebhookEndpoint
Read one exact tenant-owned endpoint, including a retained deleted one.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookEndpointResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
auto_disable_after_failures |
integer | yes | |
consecutive_failures |
integer | no | Default 0. |
created_at |
string | yes | |
deleted_at |
string or null | no | |
disabled_at |
string or null | no | |
disabled_reason |
WebhookDisabledReason or null | no | |
endpoint_id |
string | yes | |
event_catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventType | yes | |
max_concurrency |
integer | yes | |
rate_limit_per_minute |
integer | yes | |
signing_secrets |
array of WebhookSecretLifecycleResponse | no | Default []. |
status |
enum | yes | One of: active, disabled, deleted. |
triggering_delivery_id |
string or null | no | |
updated_at |
string | yes | |
url |
string | yes |
DELETE /v1/webhook-endpoints/{endpoint_id}
Section titled “DELETE /v1/webhook-endpoints/{endpoint_id}”Operation ID: deleteWebhookEndpoint
Soft-delete an endpoint and visibly fence its unfinished deliveries.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
PATCH /v1/webhook-endpoints/{endpoint_id}
Section titled “PATCH /v1/webhook-endpoints/{endpoint_id}”Operation ID: updateWebhookEndpoint
Update a destination, exact subscriptions, or bounded delivery controls.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Request body
Section titled “Request body”application/json: UpdateWebhookEndpointRequest (required)
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookEndpointResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
auto_disable_after_failures |
integer | yes | |
consecutive_failures |
integer | no | Default 0. |
created_at |
string | yes | |
deleted_at |
string or null | no | |
disabled_at |
string or null | no | |
disabled_reason |
WebhookDisabledReason or null | no | |
endpoint_id |
string | yes | |
event_catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventType | yes | |
max_concurrency |
integer | yes | |
rate_limit_per_minute |
integer | yes | |
signing_secrets |
array of WebhookSecretLifecycleResponse | no | Default []. |
status |
enum | yes | One of: active, disabled, deleted. |
triggering_delivery_id |
string or null | no | |
updated_at |
string | yes | |
url |
string | yes |
GET /v1/webhook-endpoints/{endpoint_id}/deliveries
Section titled “GET /v1/webhook-endpoints/{endpoint_id}/deliveries”Operation ID: listWebhookDeliveries
List bounded delivery state and response evidence for one endpoint.
Page an endpoint’s delivery evidence, newest first. Readable for a deleted endpoint too: the evidence is immutable and already belongs to the tenant.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
limit |
query | integer | no | Minimum 1. Maximum 100. Default 50. |
cursor |
query | string or null | no |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookDeliveryPageResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The page limit is outside its bound, or the cursor is unusable here: tampered, expired, issued for another tenant, or issued for a different collection or filter set. Every one of those fails closed with the same stable body. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
data |
array of WebhookDeliveryResponse | yes | |
next_cursor |
string or null | no |
POST /v1/webhook-endpoints/{endpoint_id}/disable
Section titled “POST /v1/webhook-endpoints/{endpoint_id}/disable”Operation ID: disableWebhookEndpoint
Disable an endpoint and visibly terminate its unfinished deliveries.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
POST /v1/webhook-endpoints/{endpoint_id}/enable
Section titled “POST /v1/webhook-endpoints/{endpoint_id}/enable”Operation ID: enableWebhookEndpoint
Return a disabled endpoint to service after revalidating its destination.
Return a disabled endpoint to service after revalidating its destination. Naturally idempotent: an endpoint that is already active is returned unchanged rather than treated as a conflict, so a retried command is safe.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookEndpointResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | The endpoint is deleted and cannot be returned to service, or just-in-time provisioning found the verified email on another account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
auto_disable_after_failures |
integer | yes | |
consecutive_failures |
integer | no | Default 0. |
created_at |
string | yes | |
deleted_at |
string or null | no | |
disabled_at |
string or null | no | |
disabled_reason |
WebhookDisabledReason or null | no | |
endpoint_id |
string | yes | |
event_catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventType | yes | |
max_concurrency |
integer | yes | |
rate_limit_per_minute |
integer | yes | |
signing_secrets |
array of WebhookSecretLifecycleResponse | no | Default []. |
status |
enum | yes | One of: active, disabled, deleted. |
triggering_delivery_id |
string or null | no | |
updated_at |
string | yes | |
url |
string | yes |
POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret
Section titled “POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret”Operation ID: rotateWebhookEndpointSecret
Begin bounded dual signing and reveal the new signing secret once.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Idempotency-Key |
header | string | yes | Pattern: ^[!-~]+$. Max length 200. |
Request body
Section titled “Request body”application/json: RotateWebhookSecretRequest or null
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json RotatedWebhookSecretResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Authentication conflict, endpoint limit, Idempotency-Key conflict, or a completed logical command whose one-time secret cannot be replayed. For secret_not_replayable, issue rotate-secret with a new Idempotency-Key. | application/json HttpErrorResponse or SecretNotReplayableResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
endpoint |
WebhookEndpointResponse | yes | One endpoint, including the reviewed reason it stopped delivering. deleted is a readable state, not an absence: a deleted endpoint keeps serving its configuration and evidence to the owning tenant for the retention period, and refuses every mutation. |
secret |
string | yes |
POST /v1/webhook-endpoints/{endpoint_id}/secret-overlap/complete
Section titled “POST /v1/webhook-endpoints/{endpoint_id}/secret-overlap/complete”Operation ID: completeWebhookEndpointSecretOverlap
Retire the outgoing webhook signer after its replacement is deployed.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json WebhookEndpointResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned resource was not found. | application/json HttpErrorResponse |
| 409 | Just-in-time provisioning conflicted: the verified email belongs to another provisioned account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | The API key’s own request rate limit was exceeded (API_KEY_RATE_LIMITED). Only keys configured with a rate limit can receive this. Retryable after Retry-After seconds; the refused request consumed no capacity. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
200 response fields
Section titled “200 response fields”| Field | Type | Required | Description |
|---|---|---|---|
auto_disable_after_failures |
integer | yes | |
consecutive_failures |
integer | no | Default 0. |
created_at |
string | yes | |
deleted_at |
string or null | no | |
disabled_at |
string or null | no | |
disabled_reason |
WebhookDisabledReason or null | no | |
endpoint_id |
string | yes | |
event_catalog_version |
CustomerEventCatalogVersion | yes | |
events |
array of CustomerEventType | yes | |
max_concurrency |
integer | yes | |
rate_limit_per_minute |
integer | yes | |
signing_secrets |
array of WebhookSecretLifecycleResponse | no | Default []. |
status |
enum | yes | One of: active, disabled, deleted. |
triggering_delivery_id |
string or null | no | |
updated_at |
string | yes | |
url |
string | yes |
POST /v1/webhook-endpoints/{endpoint_id}/test
Section titled “POST /v1/webhook-endpoints/{endpoint_id}/test”Operation ID: sendWebhookTestEvent
Queue a synthetic signed test event for this one endpoint, ten per hour at most.
Queue a synthetic, signed webhook.test event for this endpoint only. The body carries "test": true, a fresh event id and a timestamp, and no tenant or asset data. It is delivered like any other event – same signature headers, retries, attempt evidence and replay – to this endpoint and no other. At most ten per endpoint per rolling hour.
Authentication: Authorization: Bearer <API key or console session> (Authentication).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
endpoint_id |
path | string | yes | Pattern: ^whe_[a-z2-7]{16}$. |
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 202 | Successful Response | application/json WebhookTestEventResponse |
| 401 | The bearer credential is missing, malformed, expired, revoked, or otherwise invalid. Clerk sessions and scoped API keys fail identically and the body never reveals which credential was presented or whether it exists. | application/json HttpErrorResponse |
| 403 | The provider deleted this identity, or the account is deactivated. A valid session cannot authorize a tombstoned identity back into use; an API key must also grant the scope required by the operation, and an operation is not classified by the route/scope policy and is denied by default. An API key restricted to client networks is refused from any other network with the API_KEY_IP_NOT_ALLOWED envelope. |
application/json HttpErrorResponse or ErrorResponse |
| 404 | The tenant-owned endpoint was not found. | application/json HttpErrorResponse |
| 409 | The endpoint is deleted, or disabled (enable it before sending a test event), or just-in-time provisioning found the verified email on another account. | application/json HttpErrorResponse |
| 422 | The path, query, header, or JSON command is malformed, or the destination/subscription violates the closed webhook policy. The detail field is always a stable string. | application/json HttpErrorResponse |
| 429 | WEBHOOK_TEST_RATE_LIMITED: the endpoint already received 10 test events in the last hour. Or API_KEY_RATE_LIMITED: the API key’s own request rate limit was exceeded. Retryable after Retry-After seconds; a refused test queues nothing. |
application/json ErrorResponse |
| 503 | Credential verification is unavailable: Clerk session verification is not configured, no API-key pepper is enrolled, or bounded API-key verification is temporarily overloaded. Retryable. | application/json HttpErrorResponse |
202 response fields
Section titled “202 response fields”| Field | Type | Required | Description |
|---|---|---|---|
delivery_id |
string | yes | |
event_id |
string | yes | |
event_type |
const “webhook.test” | yes |