Webhook endpoints
12 operations.
-
GET
/v1/webhook-endpoints -
POST
/v1/webhook-endpoints -
GET
/v1/webhook-endpoints/{webhook_endpoint_id} -
PATCH
/v1/webhook-endpoints/{webhook_endpoint_id} -
DELETE
/v1/webhook-endpoints/{webhook_endpoint_id} -
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret -
GET
/v1/webhook-endpoints/{webhook_endpoint_id}/deliveries -
GET
/v1/webhook-deliveries/{webhook_delivery_id}/attempts -
POST
/v1/webhook-deliveries/{webhook_delivery_id}/replay -
POST
/v1/webhook-deliveries/{webhook_delivery_id}/skip -
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/replay -
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/test
GET
/v1/webhook-endpoints
The account's webhook endpoints, oldest first. Never a signing secret.
- Operation id
listWebhookEndpoints- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Answers
200 The endpoints. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
webhook_endpoints
|
array of object | yes | |
webhook_endpoints[]
|
object | yes | |
webhook_endpoints[].id
|
string | yes | |
webhook_endpoints[].url
|
string | yes | The address as checked and stored, in its canonical form. |
webhook_endpoints[].description
|
string or null | yes | |
webhook_endpoints[].event_types
|
array of string | yes | |
webhook_endpoints[].is_active
|
boolean | yes | |
webhook_endpoints[].disabled_reason
|
string or null | yes |
Why it is off: member (someone switched it off), failing (five days of only failed deliveries), gone (it answered 410), unsafe_address (its address failed the check before a delivery). Null while it is on. Switching it on again sends the deliveries that waited.
Values:
member
,
failing
,
gone
,
unsafe_address
.
|
webhook_endpoints[].previous_secret_expires_at
|
string or null | yes | While the old secret still works after a rotation, when it stops. Deliveries carry a signature with each secret until then. Limits: format date-time. |
webhook_endpoints[].failing_since
|
string or null | yes |
The first failed attempt since the last delivered one. Null while deliveries succeed. After five days of only failures the endpoint is switched off (failing).
Limits: format date-time.
|
webhook_endpoints[].report_system
|
string or null | yes | The system the receiver behind this endpoint reports as, or null when it does not report. |
webhook_endpoints[].version
|
integer | yes | |
webhook_endpoints[].created_at
|
string | yes | Limits: format date-time. |
webhook_endpoints[].updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-endpoints
Adds a webhook endpoint, switched on, and answers its signing secret once. The address is checked as written and through DNS; a refused address answers 400 with a reason. An account has at most 20 endpoints, switched on or off; one more answers 400.
- Operation id
createWebhookEndpoint- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Retry key
- Optional: send an Idempotency-Key header.
- Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
Idempotency-Key
|
header | string | no | Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
url
|
string | yes | An https address on a public host. Refused: another scheme, a port other than 443, a user name or password, an IP address, a local or reserved name, this product's own domains, and a host whose DNS answers a private, local or reserved address. Checked again before every delivery. Limits: 1 to 2048 characters. |
description
|
string or null | no | A label, such as the system that receives the events. |
event_types
|
array of string | yes | The events this endpoint receives, or ["*"] for every one, including later ones. Limits: 1 to 9 items. |
report_system
|
string or null | no | The system name the receiver behind this endpoint reports as, through PUT /v1/bookings/{booking_id}/reports/{system}. Set it when that receiver reports what it did with each booking version: a booking event delivered here and not reported within an hour is then something the product watches for. Null for an endpoint whose receiver does not report. |
Answers
201 The endpoint, with its signing secret. application/json
-
Header
Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
url
|
string | yes | The address as checked and stored, in its canonical form. |
description
|
string or null | yes | |
event_types
|
array of string | yes | |
is_active
|
boolean | yes | |
disabled_reason
|
string or null | yes |
Why it is off: member (someone switched it off), failing (five days of only failed deliveries), gone (it answered 410), unsafe_address (its address failed the check before a delivery). Null while it is on. Switching it on again sends the deliveries that waited.
Values:
member
,
failing
,
gone
,
unsafe_address
.
|
previous_secret_expires_at
|
string or null | yes | While the old secret still works after a rotation, when it stops. Deliveries carry a signature with each secret until then. Limits: format date-time. |
failing_since
|
string or null | yes |
The first failed attempt since the last delivered one. Null while deliveries succeed. After five days of only failures the endpoint is switched off (failing).
Limits: format date-time.
|
report_system
|
string or null | yes | The system the receiver behind this endpoint reports as, or null when it does not report. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
secret
|
string or null | yes |
The signing secret, whsec_ and base64, shown this once (Standard Webhooks). Null on a repeat of the same request (same Idempotency-Key): the secret is never shown again, so rotate it to get a new one.
|
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 409 | The same identifier was already used for a different request. This request is already running. |
id_conflict
,
request_in_progress
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
GET
/v1/webhook-endpoints/{webhook_endpoint_id}
One webhook endpoint. Never its signing secret.
- Operation id
getWebhookEndpoint- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
Answers
200 The endpoint. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
url
|
string | yes | The address as checked and stored, in its canonical form. |
description
|
string or null | yes | |
event_types
|
array of string | yes | |
is_active
|
boolean | yes | |
disabled_reason
|
string or null | yes |
Why it is off: member (someone switched it off), failing (five days of only failed deliveries), gone (it answered 410), unsafe_address (its address failed the check before a delivery). Null while it is on. Switching it on again sends the deliveries that waited.
Values:
member
,
failing
,
gone
,
unsafe_address
.
|
previous_secret_expires_at
|
string or null | yes | While the old secret still works after a rotation, when it stops. Deliveries carry a signature with each secret until then. Limits: format date-time. |
failing_since
|
string or null | yes |
The first failed attempt since the last delivered one. Null while deliveries succeed. After five days of only failures the endpoint is switched off (failing).
Limits: format date-time.
|
report_system
|
string or null | yes | The system the receiver behind this endpoint reports as, or null when it does not report. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|
PATCH
/v1/webhook-endpoints/{webhook_endpoint_id}
Changes a webhook endpoint's address, description, events or report system, or switches it on or off. Send the version you read. A new address, and switching an endpoint on, check the address again.
- Operation id
updateWebhookEndpoint- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
url
|
string | no | An https address on a public host. Refused: another scheme, a port other than 443, a user name or password, an IP address, a local or reserved name, this product's own domains, and a host whose DNS answers a private, local or reserved address. Checked again before every delivery. Limits: 1 to 2048 characters. |
description
|
string or null | no | A label, such as the system that receives the events. |
event_types
|
array of string | no | The events this endpoint receives, or ["*"] for every one, including later ones. Limits: 1 to 9 items. |
is_active
|
boolean | no |
false switches it off (reason member); true switches it on and checks its address again.
|
report_system
|
string or null | no | The system name the receiver behind this endpoint reports as, through PUT /v1/bookings/{booking_id}/reports/{system}. Set it when that receiver reports what it did with each booking version: a booking event delivered here and not reported within an hour is then something the product watches for. Null for an endpoint whose receiver does not report. |
Answers
200 The endpoint after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
url
|
string | yes | The address as checked and stored, in its canonical form. |
description
|
string or null | yes | |
event_types
|
array of string | yes | |
is_active
|
boolean | yes | |
disabled_reason
|
string or null | yes |
Why it is off: member (someone switched it off), failing (five days of only failed deliveries), gone (it answered 410), unsafe_address (its address failed the check before a delivery). Null while it is on. Switching it on again sends the deliveries that waited.
Values:
member
,
failing
,
gone
,
unsafe_address
.
|
previous_secret_expires_at
|
string or null | yes | While the old secret still works after a rotation, when it stops. Deliveries carry a signature with each secret until then. Limits: format date-time. |
failing_since
|
string or null | yes |
The first failed attempt since the last delivered one. Null while deliveries succeed. After five days of only failures the endpoint is switched off (failing).
Limits: format date-time.
|
report_system
|
string or null | yes | The system the receiver behind this endpoint reports as, or null when it does not report. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This was changed by someone else since it was read. |
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
DELETE
/v1/webhook-endpoints/{webhook_endpoint_id}
Deletes a webhook endpoint. Send the version you read.
- Operation id
deleteWebhookEndpoint- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It deletes. A delete is never a tool (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
version
|
query | integer | yes | Limits: at least 1. |
Answers
204 The endpoint has been deleted.
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This was changed by someone else since it was read. |
version_conflict
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret
Replaces the signing secret and answers the new one once. Send the version you read. By default the old secret keeps working for 24 hours and deliveries carry both signatures; a rotation during that time drops the older secret.
- Operation id
rotateWebhookSecret- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It mints a capability, credential or secret that outlives the grant and is later checked against the member's full role (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
keep_previous
|
boolean | no | Default true: the old secret keeps working for 24 hours, and deliveries carry both signatures. false: it stops at once, for a secret that leaked. |
Answers
200 The endpoint, with its new signing secret. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
url
|
string | yes | The address as checked and stored, in its canonical form. |
description
|
string or null | yes | |
event_types
|
array of string | yes | |
is_active
|
boolean | yes | |
disabled_reason
|
string or null | yes |
Why it is off: member (someone switched it off), failing (five days of only failed deliveries), gone (it answered 410), unsafe_address (its address failed the check before a delivery). Null while it is on. Switching it on again sends the deliveries that waited.
Values:
member
,
failing
,
gone
,
unsafe_address
.
|
previous_secret_expires_at
|
string or null | yes | While the old secret still works after a rotation, when it stops. Deliveries carry a signature with each secret until then. Limits: format date-time. |
failing_since
|
string or null | yes |
The first failed attempt since the last delivered one. Null while deliveries succeed. After five days of only failures the endpoint is switched off (failing).
Limits: format date-time.
|
report_system
|
string or null | yes | The system the receiver behind this endpoint reports as, or null when it does not report. |
version
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
secret
|
string or null | yes |
The signing secret, whsec_ and base64, shown this once (Standard Webhooks). Null on a repeat of the same request (same Idempotency-Key): the secret is never shown again, so rotate it to get a new one.
|
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This was changed by someone else since it was read. |
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
GET
/v1/webhook-endpoints/{webhook_endpoint_id}/deliveries
One endpoint's deliveries, newest first, optionally of one status. Pass next_cursor as cursor for the next page.
- Operation id
listWebhookDeliveries- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
status
|
query | string | no |
Values:
pending
,
blocked
,
in_flight
,
delivered
,
dead
,
canceled
.
|
cursor
|
query | string | no | |
limit
|
query | integer | no | Limits: at least 1, at most 100. |
Answers
200 One page of deliveries. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
deliveries
|
array of object | yes | |
deliveries[]
|
object | yes | |
deliveries[].id
|
string | yes | |
deliveries[].event_id
|
string | yes |
The event's id: the webhook-id header of every attempt.
|
deliveries[].event_type
|
string | yes | |
deliveries[].endpoint_id
|
string | yes | |
deliveries[].subject_type
|
string | yes |
booking, routing_submission or webhook_delivery.
|
deliveries[].subject_id
|
string | yes | |
deliveries[].sequence
|
integer | yes | The event's place among its subject's events. |
deliveries[].status
|
string | yes |
pending (waiting for its time; no time while its endpoint is off), blocked (an earlier event of the same booking has not reached this endpoint yet), in_flight, delivered, dead (retries used up or refused; its followers wait until it is replayed or skipped), canceled (skipped).
Values:
pending
,
blocked
,
in_flight
,
delivered
,
dead
,
canceled
.
|
deliveries[].attempts
|
integer | yes | |
deliveries[].next_attempt_at
|
string or null | yes | Limits: format date-time. |
deliveries[].last_http_status
|
integer or null | yes | |
deliveries[].last_error_code
|
string or null | yes |
Why it did not deliver: http_status (an answer other than 2xx; see the status), redirect (a 3xx, never followed), gone (410), timeout, network_error, lease_expired (the attempt's result was lost; it may have arrived), not_sent (it ran out of time before the request), a reason of the address check (points_inward, does_not_resolve, ...), skipped (someone skipped it), or expired (still not delivered when the event reached its retention age, so it was given up). Null when nothing failed.
Values:
http_status
,
redirect
,
gone
,
timeout
,
network_error
,
lease_expired
,
not_sent
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
malformed
,
skipped
,
expired
.
|
deliveries[].delivered_at
|
string or null | yes | Limits: format date-time. |
deliveries[].replay_count
|
integer | yes | |
deliveries[].created_at
|
string | yes | Limits: format date-time. |
deliveries[].updated_at
|
string | yes | Limits: format date-time. |
next_cursor
|
string or null | yes |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|
GET
/v1/webhook-deliveries/{webhook_delivery_id}/attempts
One delivery and every attempt it made, in order: when, how long, the status and an error code. Never a response body.
- Operation id
listWebhookAttempts- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_delivery_id
|
path | string | yes | Limits: pattern ^dlv_[0-9a-z]{26}$. |
Answers
200 The delivery and its attempts. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
delivery
|
object | yes | |
delivery.id
|
string | yes | |
delivery.event_id
|
string | yes |
The event's id: the webhook-id header of every attempt.
|
delivery.event_type
|
string | yes | |
delivery.endpoint_id
|
string | yes | |
delivery.subject_type
|
string | yes |
booking, routing_submission or webhook_delivery.
|
delivery.subject_id
|
string | yes | |
delivery.sequence
|
integer | yes | The event's place among its subject's events. |
delivery.status
|
string | yes |
pending (waiting for its time; no time while its endpoint is off), blocked (an earlier event of the same booking has not reached this endpoint yet), in_flight, delivered, dead (retries used up or refused; its followers wait until it is replayed or skipped), canceled (skipped).
Values:
pending
,
blocked
,
in_flight
,
delivered
,
dead
,
canceled
.
|
delivery.attempts
|
integer | yes | |
delivery.next_attempt_at
|
string or null | yes | Limits: format date-time. |
delivery.last_http_status
|
integer or null | yes | |
delivery.last_error_code
|
string or null | yes |
Why it did not deliver: http_status (an answer other than 2xx; see the status), redirect (a 3xx, never followed), gone (410), timeout, network_error, lease_expired (the attempt's result was lost; it may have arrived), not_sent (it ran out of time before the request), a reason of the address check (points_inward, does_not_resolve, ...), skipped (someone skipped it), or expired (still not delivered when the event reached its retention age, so it was given up). Null when nothing failed.
Values:
http_status
,
redirect
,
gone
,
timeout
,
network_error
,
lease_expired
,
not_sent
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
malformed
,
skipped
,
expired
.
|
delivery.delivered_at
|
string or null | yes | Limits: format date-time. |
delivery.replay_count
|
integer | yes | |
delivery.created_at
|
string | yes | Limits: format date-time. |
delivery.updated_at
|
string | yes | Limits: format date-time. |
attempts
|
array of object | yes | |
attempts[]
|
object | yes | |
attempts[].attempt_no
|
integer | yes | |
attempts[].started_at
|
string | yes | Limits: format date-time. |
attempts[].duration_ms
|
integer or null | yes | |
attempts[].http_status
|
integer or null | yes | |
attempts[].error_code
|
string or null | yes |
Why it did not deliver: http_status (an answer other than 2xx; see the status), redirect (a 3xx, never followed), gone (410), timeout, network_error, lease_expired (the attempt's result was lost; it may have arrived), not_sent (it ran out of time before the request), a reason of the address check (points_inward, does_not_resolve, ...), skipped (someone skipped it), or expired (still not delivered when the event reached its retention age, so it was given up). Null when nothing failed.
Values:
http_status
,
redirect
,
gone
,
timeout
,
network_error
,
lease_expired
,
not_sent
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
malformed
,
skipped
,
expired
.
|
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-deliveries/{webhook_delivery_id}/replay
Sends a dead (or skipped) delivery again: the same id and the same bytes, with a fresh retry schedule. Deliveries of the same booking that waited behind it follow in order.
- Operation id
replayWebhookDelivery- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_delivery_id
|
path | string | yes | Limits: pattern ^dlv_[0-9a-z]{26}$. |
Answers
200 The delivery, pending again. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
event_id
|
string | yes |
The event's id: the webhook-id header of every attempt.
|
event_type
|
string | yes | |
endpoint_id
|
string | yes | |
subject_type
|
string | yes |
booking, routing_submission or webhook_delivery.
|
subject_id
|
string | yes | |
sequence
|
integer | yes | The event's place among its subject's events. |
status
|
string | yes |
pending (waiting for its time; no time while its endpoint is off), blocked (an earlier event of the same booking has not reached this endpoint yet), in_flight, delivered, dead (retries used up or refused; its followers wait until it is replayed or skipped), canceled (skipped).
Values:
pending
,
blocked
,
in_flight
,
delivered
,
dead
,
canceled
.
|
attempts
|
integer | yes | |
next_attempt_at
|
string or null | yes | Limits: format date-time. |
last_http_status
|
integer or null | yes | |
last_error_code
|
string or null | yes |
Why it did not deliver: http_status (an answer other than 2xx; see the status), redirect (a 3xx, never followed), gone (410), timeout, network_error, lease_expired (the attempt's result was lost; it may have arrived), not_sent (it ran out of time before the request), a reason of the address check (points_inward, does_not_resolve, ...), skipped (someone skipped it), or expired (still not delivered when the event reached its retention age, so it was given up). Null when nothing failed.
Values:
http_status
,
redirect
,
gone
,
timeout
,
network_error
,
lease_expired
,
not_sent
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
malformed
,
skipped
,
expired
.
|
delivered_at
|
string or null | yes | Limits: format date-time. |
replay_count
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This cannot be done while something else depends on it. |
conflict
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-deliveries/{webhook_delivery_id}/skip
Gives up a dead delivery on purpose. The deliveries of the same booking that waited behind it go on. A skipped delivery can still be replayed.
- Operation id
skipWebhookDelivery- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_delivery_id
|
path | string | yes | Limits: pattern ^dlv_[0-9a-z]{26}$. |
Answers
200 The delivery, skipped. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
id
|
string | yes | |
event_id
|
string | yes |
The event's id: the webhook-id header of every attempt.
|
event_type
|
string | yes | |
endpoint_id
|
string | yes | |
subject_type
|
string | yes |
booking, routing_submission or webhook_delivery.
|
subject_id
|
string | yes | |
sequence
|
integer | yes | The event's place among its subject's events. |
status
|
string | yes |
pending (waiting for its time; no time while its endpoint is off), blocked (an earlier event of the same booking has not reached this endpoint yet), in_flight, delivered, dead (retries used up or refused; its followers wait until it is replayed or skipped), canceled (skipped).
Values:
pending
,
blocked
,
in_flight
,
delivered
,
dead
,
canceled
.
|
attempts
|
integer | yes | |
next_attempt_at
|
string or null | yes | Limits: format date-time. |
last_http_status
|
integer or null | yes | |
last_error_code
|
string or null | yes |
Why it did not deliver: http_status (an answer other than 2xx; see the status), redirect (a 3xx, never followed), gone (410), timeout, network_error, lease_expired (the attempt's result was lost; it may have arrived), not_sent (it ran out of time before the request), a reason of the address check (points_inward, does_not_resolve, ...), skipped (someone skipped it), or expired (still not delivered when the event reached its retention age, so it was given up). Null when nothing failed.
Values:
http_status
,
redirect
,
gone
,
timeout
,
network_error
,
lease_expired
,
not_sent
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
malformed
,
skipped
,
expired
.
|
delivered_at
|
string or null | yes | Limits: format date-time. |
replay_count
|
integer | yes | |
created_at
|
string | yes | Limits: format date-time. |
updated_at
|
string | yes | Limits: format date-time. |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This cannot be done while something else depends on it. |
conflict
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/replay
Sends the dead deliveries of this endpoint made in a time range again, oldest first, each with a fresh retry schedule: at most 500 a call. Answers how many, and more when some are left: call it again for the rest.
- Operation id
replayWebhookDeliveries- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
from
|
string | yes | Deliveries made at or after this instant. Limits: format date-time. |
to
|
string | yes |
Deliveries made before this instant. At most 31 days after from.
Limits: format date-time.
|
Answers
200 How many deliveries are pending again, and whether more are left. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
replayed
|
integer | yes | |
more
|
boolean | yes |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The body is not valid JSON. The request is not valid. |
invalid_json
,
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
POST
/v1/webhook-endpoints/{webhook_endpoint_id}/test
Sends a test event (webhook.test, a fixed body that names no booking and no person) to the endpoint now, signed like every delivery, and answers how it went. Nothing is stored or retried.
- Operation id
testWebhookEndpoint- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
webhooks.manage - Assistant tool
- No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
webhook_endpoint_id
|
path | string | yes | Limits: pattern ^whe_[0-9a-z]{26}$. |
Answers
200 How the test went. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
event_id
|
string | yes |
The test event's id, as sent in webhook-id. Nothing is stored.
|
outcome
|
string | yes |
delivered (2xx), http_status (another answer; see the status), redirect, timeout, network_error, not_sent, stopped (sending is stopped in this environment; nothing was sent), or a reason of the address check.
|
http_status
|
integer or null | yes | |
duration_ms
|
integer or null | yes |
Refusals
| Status | Meaning | Codes |
|---|---|---|
| 400 | The request is not valid. |
invalid_request
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. Choose an account to act in first. |
forbidden
,
no_active_account
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|