Copy page
View as Markdown View this page as plain textOpen in Claude Ask questions about this page
API reference

Webhook endpoints

URLs that receive signed event deliveries.

Create

POST/v1/webhook-endpoints201 Created

The create response returns signing_secret once. Store it for signature verification; retrieve, list, and update responses do not reveal it.

Request body

FieldTypeNotes
urlrequiredstring
descriptionstring
subscribed_eventsrequiredstring[]

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_endpoint"
urlrequiredstring
descriptionrequiredstring | null
subscribed_eventsrequiredstring[]
statusrequired"active" | "disabled"
disabled_reasonrequiredstring | null
disabled_detailrequiredobject | null
last_failure_atrequiredstring<ISO-8601> | null
last_success_atrequiredstring<ISO-8601> | null
environmentrequired"sandbox" | "production"
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
signing_secretrequiredstring

List

GET/v1/webhook-endpoints

Query

FieldTypeNotes
limitrequiredinteger
Maximum number of items to return. Defaults to 20; maximum 100.
range 1..100
starting_afterstring
Opaque cursor from the previous response next_cursor.

Response

FieldTypeNotes
objectrequired"list"
datarequiredobject[]
has_morerequiredboolean
next_cursorrequiredstring | null

Retrieve

GET/v1/webhook-endpoints/{id}

Every endpoint response includes nullable disabled_detail. An auto-disabled endpoint reports only its triggering last_status_code (or null if no response arrived) and failure_class; active, manually disabled, and legacy endpoints return null. It never includes breaker counters, internal events, or a signing secret.

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_endpoint"
urlrequiredstring
descriptionrequiredstring | null
subscribed_eventsrequiredstring[]
statusrequired"active" | "disabled"
disabled_reasonrequiredstring | null
disabled_detailrequiredobject | null
last_failure_atrequiredstring<ISO-8601> | null
last_success_atrequiredstring<ISO-8601> | null
environmentrequired"sandbox" | "production"
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Update

PATCH/v1/webhook-endpoints/{id}

Setting status to active re-enables an endpoint the auto-disable breaker turned off after 20 consecutive failed deliveries, clearing its consecutive-failure counter, disabled_reason, and disabled_detail; this route is the only way to re-enable one. It does not rotate the signing secret, replay terminal events, or send a test delivery.

Request body

FieldTypeNotes
urlstring
descriptionstring | null
subscribed_eventsstring[]
status"active" | "disabled"

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_endpoint"
urlrequiredstring
descriptionrequiredstring | null
subscribed_eventsrequiredstring[]
statusrequired"active" | "disabled"
disabled_reasonrequiredstring | null
disabled_detailrequiredobject | null
last_failure_atrequiredstring<ISO-8601> | null
last_success_atrequiredstring<ISO-8601> | null
environmentrequired"sandbox" | "production"
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Rotate signing secret

POST/v1/webhook-endpoints/{id}/rotate-signing-secret

Returns the new signing_secret once. Existing endpoint details continue to hide signing secrets.

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_endpoint"
urlrequiredstring
descriptionrequiredstring | null
subscribed_eventsrequiredstring[]
statusrequired"active" | "disabled"
disabled_reasonrequiredstring | null
disabled_detailrequiredobject | null
last_failure_atrequiredstring<ISO-8601> | null
last_success_atrequiredstring<ISO-8601> | null
environmentrequired"sandbox" | "production"
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
signing_secretrequiredstring

Test delivery

POST/v1/webhook-endpoints/{id}/test202 Accepted

Sends an empty, idempotent direct probe to one active endpoint and returns a durable pending receipt. Store webhook_event_id, then retrieve that event to inspect its delivery status and first-attempt evidence.

A missing, deleted, or out-of-scope endpoint returns 404 webhook_endpoint_not_found. A disabled endpoint returns 409 webhook_endpoint_disabled; repair the receiver and re-enable it with PATCH /v1/webhook-endpoints/{id} and status: active. Each endpoint allows five test requests per minute; on 429 rate_limited, honor Retry-After and error.retry_after_ms.

202 response

FieldTypeNotes
objectrequired"webhook_test"
webhook_event_idrequiredstring
webhook_endpoint_idrequiredstring
statusrequired"pending"

Delete

DELETE/v1/webhook-endpoints/{id}

List events

GET/v1/webhook-events

Query

FieldTypeNotes
limitrequiredinteger
Maximum number of items to return. Defaults to 20; maximum 100.
range 1..100
starting_afterstring
Opaque cursor from the previous response next_cursor.
event_typestring
len 1..∞
event_typesstring | string[]
webhook_endpoint_idstring
status"pending" | "delivered" | "failed"

Response

FieldTypeNotes
objectrequired"list"
datarequiredobject[]
has_morerequiredboolean
next_cursorrequiredstring | null

Listen for events

Polls customer-visible events oldest first for local development companions and conformance probes. Sandbox keys can call directly. Production keys must create a short-lived listen session and pass listen_session_id; production reads are bounded to events created after that session opened. The route supports event_type or event_types, bounded long polling with wait_ms, and standard 429 rate-limit errors with Retry-After. Use limit to cap each page, pass the previous next_cursor as cursor, and use start_at=tail when the first poll should skip existing events. Pass webhook_endpoint_id to attach signature_preview, which includes the exact raw body, timestamp, signature, and Tyxter headers generated with that endpoint secret.

For message.received interactive replies, each listen item stores the webhook envelope under payload. Read button/list selections at payload.data.content.interactive.button_reply or payload.data.content.interactive.list_reply. Sender and recipient live at payload.data.sender and payload.data.recipient; there is no top-level payload.from.

GET/v1/webhook-events/listen

Query

FieldTypeNotes
limitrequiredinteger
Maximum number of events to return per poll. Defaults to 20; maximum 100.
range 1..100
cursorstring
Opaque cursor from the previous listen response next_cursor.
start_atrequired"oldest" | "tail"
Initial listen position when cursor is omitted. "oldest" replays retained events; "tail" starts after the current stream tail.
event_typestring
len 1..∞
event_typesstring | string[]
wait_msrequiredinteger
Long-poll wait budget in milliseconds. Defaults to 0; maximum 25000.
range 0..25000
webhook_endpoint_idstring
Optional endpoint id used to filter listen events to that endpoint subscription and attach a signature_preview computed with that endpoint signing secret.
listen_session_idstring
Required for production API keys. Create a short-lived session with POST /v1/webhook-events/listen-sessions before polling.

Response

FieldTypeNotes
objectrequired"webhook_event_listen"
datarequiredobject[]
has_morerequiredboolean
next_cursorrequiredstring | null
next_poll_after_msinteger
range 0..9007199254740991

Create listen session

POST/v1/webhook-events/listen-sessions201 Created

Production-only diagnostic lease for temporary no-public-URL polling. Sessions default to five minutes, cannot exceed five minutes, are rate-limited, and should be disabled when the probe finishes.

Request body

FieldTypeNotes
ttl_secondsrequiredinteger
range 30..300
reasonstring
len 1..200

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_listen_session"
environmentrequired"production"
statusrequired"active" | "disabled" | "expired"
expires_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disabled_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
trace_idrequiredstring
poll_endpointrequired"/v1/webhook-events/listen"
retrieve_endpointrequired"/v1/webhook-events/listen/:outbox_event_id"

Disable listen session

DELETE/v1/webhook-events/listen-sessions/{listen_session_id}

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_listen_session"
environmentrequired"production"
statusrequired"active" | "disabled" | "expired"
expires_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
disabled_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
trace_idrequiredstring
poll_endpointrequired"/v1/webhook-events/listen"
retrieve_endpointrequired"/v1/webhook-events/listen/:outbox_event_id"

Retrieve listen event

GET/v1/webhook-events/listen/{outbox_event_id}

Query

FieldTypeNotes
webhook_endpoint_idstring
Optional endpoint id used to attach a signature_preview computed with that endpoint signing secret.
listen_session_idstring
Required for production API keys. The requested outbox event must have been created after the listen session opened.

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_event"
endpoint_idrequiredstring | null
typerequiredstring
source_typerequiredstring
source_idrequiredstring
payloadrequiredunknown | null
The delivered event body. Null once contact erasure or the retention sweep cleared the stored payload — the event log row survives, its content does not.
statusrequired"pending" | "delivered" | "failed"
trace_idrequiredstring
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
attemptsrequiredobject[]
signature_previewobject

Retrieve event

GET/v1/webhook-events/{id}

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_event"
endpoint_idrequiredstring | null
typerequiredstring
source_typerequiredstring
source_idrequiredstring
payloadrequiredunknown | null
The delivered event body. Null once contact erasure or the retention sweep cleared the stored payload — the event log row survives, its content does not.
statusrequired"pending" | "delivered" | "failed"
trace_idrequiredstring
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
attemptsrequiredobject[]
signature_previewobject

Resend event

POST/v1/webhook-events/{id}/resend

Response

FieldTypeNotes
idrequiredstring
statusrequired"pending" | "succeeded" | "failed"
attemptrequiredinteger
range 1..9007199254740991
status_coderequiredinteger | null
response_body_redactedrequiredstring | null
error_messagerequiredstring | null
next_retry_atrequiredstring<ISO-8601> | null
created_atrequiredstring<ISO-8601>
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Bulk resend events

POST/v1/webhook-events/bulk-resend

Request body

FieldTypeNotes
webhook_event_idsstring[]
event_typestring
len 1..∞
status"pending" | "delivered" | "failed"
limitinteger
range 1..100

Response

FieldTypeNotes
objectrequired"webhook_bulk_resend"
requestedrequiredinteger
range 0..9007199254740991
enqueuedrequiredinteger
range 0..9007199254740991
skippedrequiredinteger
range 0..9007199254740991
attemptsrequiredobject[]