Webhook Deliveries

Register where events are delivered, roll the signing secret without dropping a delivery, and see how the destination is behaving.

List webhook delivery history

GET/v1/webhook_deliveries

Retry a pending webhook delivery now

POST/v1/webhook_deliveries/{delivery}/retry

ModelsExpand Collapse

Delivery object { id, attempt_history_complete, attempts, 11 more }

One webhook delivery and every retained applied attempt belonging to it.

id: string

attempt_history_complete: boolean

True only when every spent attempt has a retained applied verdict and collection covered this delivery from creation.

attempts: array of DeliveryAttempt { attempt, attempt_completed_at, attempt_started_at, 9 more }

attempt: number

The spent attempt number. Gaps mean a lease expired without an applied verdict.

formatint32

attempt_completed_at: string

formatdate-time

attempt_started_at: string

formatdate-time

destination: string

Scheme, host and effective port only. Path, query, fragment and credentials are never returned.

http_status: number

Response status, or null when no response was received.

formatint32

phase: string

pre_dial when no request began, or wire after the HTTP round trip began.

reason_code: string

A bounded machine reason. Treat unknown values as unknown.

verdict: string

delivered, retryable, or permanent. Treat unknown values as an unavailable verdict.

wire_completed_at: string

formatdate-time

wire_duration_ms: number

formatint64

wire_started_at: string

formatdate-time

trace_id: optional string

W3C trace id when one was recorded. Correlation only; never authorization.

created_at: string

formatdate-time

endpoint_id: string

event_id: string

event_kind: string

observed_attempt_count: number

Applied attempt verdicts retained below.

formatint32

seq_from: number

formatint64

seq_to: number

formatint64

spent_attempt_count: number

Attempts spent by the delivery machine, including leases that expired without an applied verdict.

formatint32

state: string

pending, delivering, delivered, permanent_refusal, or retry_exhausted.

chat_id: optional string

next_attempt_at: optional string

Present only while state is pending: the instant the next attempt becomes due. A value in the future is a delivery backing off after a failed attempt; a value at or before now is a delivery that is due and waiting — usually behind an earlier delivery to the same endpoint and chat, which is delivered in order. POST /v1/webhook_deliveries/{delivery}/retry moves a future value to now.

formatdate-time

DeliveryAttempt object { attempt, attempt_completed_at, attempt_started_at, 9 more }

One applied attempt to deliver an account event to a webhook endpoint.

attempt: number

The spent attempt number. Gaps mean a lease expired without an applied verdict.

formatint32

attempt_completed_at: string

formatdate-time

attempt_started_at: string

formatdate-time

destination: string

Scheme, host and effective port only. Path, query, fragment and credentials are never returned.

http_status: number

Response status, or null when no response was received.

formatint32

phase: string

pre_dial when no request began, or wire after the HTTP round trip began.

reason_code: string

A bounded machine reason. Treat unknown values as unknown.

verdict: string

delivered, retryable, or permanent. Treat unknown values as an unavailable verdict.

wire_completed_at: string

formatdate-time

wire_duration_ms: number

formatint64

wire_started_at: string

formatdate-time

trace_id: optional string

W3C trace id when one was recorded. Correlation only; never authorization.

DeliveryPage object { attempt_history_coverage_started_at, data, has_more, 3 more }

A bounded page of webhook deliveries. Parent deliveries are never split across pages.

attempt_history_coverage_started_at: string

Inclusive instant when attempt-history collection began. Earlier deliveries cannot claim complete attempt history.

formatdate-time

data: array of Delivery { id, attempt_history_complete, attempts, 11 more }

id: string

attempt_history_complete: boolean

True only when every spent attempt has a retained applied verdict and collection covered this delivery from creation.

attempts: array of DeliveryAttempt { attempt, attempt_completed_at, attempt_started_at, 9 more }

attempt: number

The spent attempt number. Gaps mean a lease expired without an applied verdict.

formatint32

attempt_completed_at: string

formatdate-time

attempt_started_at: string

formatdate-time

destination: string

Scheme, host and effective port only. Path, query, fragment and credentials are never returned.

http_status: number

Response status, or null when no response was received.

formatint32

phase: string

pre_dial when no request began, or wire after the HTTP round trip began.

reason_code: string

A bounded machine reason. Treat unknown values as unknown.

verdict: string

delivered, retryable, or permanent. Treat unknown values as an unavailable verdict.

wire_completed_at: string

formatdate-time

wire_duration_ms: number

formatint64

wire_started_at: string

formatdate-time

trace_id: optional string

W3C trace id when one was recorded. Correlation only; never authorization.

created_at: string

formatdate-time

endpoint_id: string

event_id: string

event_kind: string

observed_attempt_count: number

Applied attempt verdicts retained below.

formatint32

seq_from: number

formatint64

seq_to: number

formatint64

spent_attempt_count: number

Attempts spent by the delivery machine, including leases that expired without an applied verdict.

formatint32

state: string

pending, delivering, delivered, permanent_refusal, or retry_exhausted.

chat_id: optional string

next_attempt_at: optional string

formatdate-time

has_more: boolean

older_successful_history_may_have_been_swept: boolean

True when successful delivery detail may have been swept from this account partition.

successful_history_incomplete_through: string

Inclusive creation-time horizon through which successful delivery detail may be incomplete.

formatdate-time

next_cursor: optional string