List delivery attempts
GET /v1/webhooks/{webhook_id}/attempts
Read as Markdown ↗GET /v1/webhooks/{webhook_id}/attempts
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Lists delivery attempts the provider made toward this webhook, newest first, with the event each attempt carried. A success is a 2xx received within the provider's timeout: an acknowledgement from the receiver, not evidence that the receiver finished processing. failed attempts coexist with scheduled retries until the retry schedule is exhausted, after which persistent failure disables the webhook. response_snippet is the untrusted start of the receiver's response body as plain text.
History covers the provider's retained window only; older attempts are not listed. An unavailable provider returns 503 webhook_history_unavailable rather than an empty page. Page with limit and the returned next_cursor on this URL.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
webhook_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
limit | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | Opaque cursor returned by the same listing. Stop when next_cursor is null. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/webhooks/WEBHOOK_ID/attempts" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"webhook_id": "55555555-5555-4555-8555-555555555555",
"attempts": [
{
"id": "atmpt_EXAMPLE",
"webhook_id": "55555555-5555-4555-8555-555555555555",
"event_id": "66666666-6666-4666-8666-666666666666",
"event_type": "message.received",
"status": "success",
"trigger": "scheduled",
"response_status_code": 204,
"response_duration_ms": 120,
"response_snippet": "",
"response_truncated": false,
"attempted_at": "2026-10-01T00:00:01.000Z"
}
],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
invalid_cursor: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 503
webhook_history_unavailable: Delivery history could not be read from the webhook provider. Retry later; an unavailable history is not an empty one.
webhooks_unavailable: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: WebhookAttemptList
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
webhook_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
attempts | Yes | array of WebhookAttempt | |
next_cursor | Yes | string or null |
Schema: WebhookAttempt
A success is a timely 2xx from the receiver: acknowledgement, not completed processing. Failed attempts coexist with scheduled retries until the provider's schedule is exhausted. webhook_id is null on the event view when that webhook has since been deleted.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Provider attempt ID. |
webhook_id | Yes | string or null | |
event_id | Yes | string or null | |
event_type | Yes | WebhookEventType or null | |
status | Yes | "success" or "pending" or "sending" or "failed" or "canceled" | |
trigger | Yes | "scheduled" or "manual" | |
response_status_code | Yes | integer | Zero when no HTTP response was obtained. minimum: 0 |
response_duration_ms | Yes | integer | minimum: 0 |
response_snippet | Yes | string | Start of the receiver's response body as plain text, control characters removed. Untrusted content. maxLength: 200 |
response_truncated | Yes | boolean | |
attempted_at | Yes | string | format: date-time |
Schema: WebhookEventType
message.received: received mail became ready to read. message.sent: provider acceptance of a send was persisted; not delivery.
"message.received" or "message.sent"
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1