List webhooks
GET /v1/webhooks
Read as Markdown ↗GET /v1/webhooks
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Lists every webhook of the account with its live provider configuration and state. Configuration (url, event_types, inbox_ids, enabled, updated_at) is read from the delivery provider on each call. When the provider cannot be read, each webhook still appears with its ID, status: "unknown" and null configuration, so you can identify and delete it.
status is the provider's live state. disabled is reached either by your own edit or by the provider after persistent delivery failures; it never flips back on its own, so edit with enabled: true when the receiver is repaired. pending_operation is separate from status: it names unconfirmed creation, removal or rotation work.
Secrets are never listed. Use this listing to recover from a lost creation response: match the URL you added, then retrieve the secret instead of adding again. See Receive webhook notifications.
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" \
--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.
{
"webhooks": []
}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 503
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: WebhookList
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
webhooks | Yes | array of Webhook |
Schema: Webhook
status is the provider's live state: active delivers, disabled does not (set by you or by the provider after persistent failures), pending means creation or removal is unconfirmed, unknown means the provider could not be read or no longer has the endpoint. pending_operation is distinct from status and names unconfirmed work. Secrets never appear here.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
created_at | Yes | string | UTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
url | Yes | string or null | |
event_types | Yes | array of WebhookEventType or null | |
inbox_ids | Yes | array of string or null | |
deleted_inbox_ids | Yes | array of string | Scoped inbox IDs that are no longer live inboxes. They match nothing; re-scope to remove them. |
enabled | Yes | boolean or null | |
updated_at | Yes | string or null | |
status | Yes | "active" or "disabled" or "pending" or "unknown" | |
pending_operation | Yes | object or null | |
secret_rotated_at | Yes | string or null | |
previous_secret_expires_at | Yes | string or null |
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