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
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}'}

Response

FieldTypeNotes
idrequiredstring
objectrequired"webhook_endpoint"
urlrequiredstring
descriptionrequiredstring | null
subscribed_eventsrequiredstring[]
statusrequired"active" | "disabled"
disabled_reasonrequiredstring | 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}'}

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
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
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

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
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
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[]