Webhook deliveries
What went out to an endpoint, what waits for a retry and what failed, with the responses of the receiver; a delivery can be retried.
Webhook deliveries
Objects
WebhookDelivery
idintegerrequiredID of the record, unique among records of its kind in the store.
endpoint_idintegerrequiredID of the webhook endpoint.
event_idinteger or nullrequiredID of the event in GET /v1/events, the same as webhook-id of the delivery; null for a test event.
event_typestringrequiredType of the event; ping for a test event.
statusstringrequiredpending — waiting for an attempt; succeeded — the receiver responded 2xx; failed — the retries are exhausted.
- Values:
pendingsucceededfailed
attempt_countintegerrequiredAttempts made.
next_attempt_atstring (date-time) or nullrequiredWhen the next attempt goes; null when the delivery is closed.
last_attemptobject or nullThe last attempt; null before the first. Only in the list.
Fields · 7
numberintegerrequiredNumber of the attempt, from 1.
manualbooleanrequiredThe attempt was made on a retry request, not by the schedule.
started_atstring (date-time)requiredWhen the attempt started.
duration_msintegerrequiredHow long the attempt took, in milliseconds.
response_statusinteger or nullrequiredHTTP status the receiver responded with; null when there was no response.
response_bodystring or nullrequiredBeginning of the response body of the receiver; null when there was none.
errorstring or nullrequiredWhy the attempt failed; null when the receiver responded 2xx. redirect — a 3xx response, redirects are not followed; http_error — another status; timeout — no response in 10 seconds; tls, connection, dns, unreachable — the network; blocked — the address leads to an internal network; invalid_url — the address does not pass the check.
- Values:
invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
attemptsarray of objectAll attempts in order. Only for one delivery.
Fields · 7
numberintegerrequiredNumber of the attempt, from 1.
manualbooleanrequiredThe attempt was made on a retry request, not by the schedule.
started_atstring (date-time)requiredWhen the attempt started.
duration_msintegerrequiredHow long the attempt took, in milliseconds.
response_statusinteger or nullrequiredHTTP status the receiver responded with; null when there was no response.
response_bodystring or nullrequiredBeginning of the response body of the receiver; null when there was none.
errorstring or nullrequiredWhy the attempt failed; null when the receiver responded 2xx. redirect — a 3xx response, redirects are not followed; http_error — another status; timeout — no response in 10 seconds; tls, connection, dns, unreachable — the network; blocked — the address leads to an internal network; invalid_url — the address does not pass the check.
- Values:
invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
Deliveries of a webhook endpoint: what went out, what awaits a retry, what failed
get/webhook-endpoints/{endpoint}/deliveries
Scope: webhooks:read
Parameters
Path
endpointintegerrequiredID of the webhook endpoint.
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
statusstringOnly deliveries in this status.
- Values:
pendingsucceededfailed
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/deliveries" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}A webhook delivery with all attempts and receiver responses
get/webhook-deliveries/{delivery}
Scope: webhooks:read
Parameters
Path
deliveryintegerrequiredID of the webhook delivery.
Responses
200Success
application/json
Returns WebhookDelivery
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/webhook-deliveries/{delivery}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Send a ping test event to the endpoint — one attempt signed with the current secret
post/webhook-endpoints/{endpoint}/test
Scope: webhooks:write
Parameters
Path
endpointintegerrequiredID of the webhook endpoint.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns WebhookDelivery
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/test" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Retry the delivery now — the same body and the same webhook-id
post/webhook-deliveries/{delivery}/retry
Scope: webhooks:write
Parameters
Path
deliveryintegerrequiredID of the webhook delivery.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
202Accepted: the outcome is at the Location URL
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns WebhookDelivery
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/webhook-deliveries/{delivery}/retry" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}