# Read a webhook GET /v1/webhooks/{webhook_id} Source: https://cherami.to/docs/api/webhooks/get-webhook {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `GET /v1/webhooks/{webhook_id}` Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. Returns one owned webhook with its live provider configuration and state, exactly as in [the listing](https://cherami.to/docs/api/webhooks/list-webhooks). Missing, deleted and other-account webhooks return `404`. A webhook whose provider endpoint has disappeared reads `status: "unknown"` with null configuration; delete it and add again. ## Parameters [#parameters] | Parameter | Location | Required | Type | Meaning | | ------------ | -------- | -------- | ------ | ---------------------------------------------- | | `webhook_id` | path | Yes | string | Owned Cherami resource ID returned by the API. | ## curl example [#curl-example] Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment. ```sh curl --silent --show-error --include --request GET \ "https://cherami.to/v1/webhooks/WEBHOOK_ID" \ --header "Authorization: Bearer $CHERAMI_API_KEY" ``` ## Responses [#responses] ### HTTP 200 [#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](#schema-webhook) ```json { "id": "55555555-5555-4555-8555-555555555555", "created_at": "2026-10-01T00:00:00.000Z", "url": "https://example.com/hooks/cherami", "event_types": [ "message.received" ], "inbox_ids": [ "11111111-1111-4111-8111-111111111111" ], "deleted_inbox_ids": [], "enabled": true, "updated_at": "2026-10-01T00:00:00.000Z", "status": "active", "pending_operation": null, "secret_rotated_at": null, "previous_secret_expires_at": null } ``` ### HTTP 401 [#http-401] `unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost. * `X-Request-ID`: Support correlation ID, not an idempotency key. * `WWW-Authenticate`: `"Bearer"` Content type: `application/json`. [Error](#schema-error) ### HTTP 404 [#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`. [Error](#schema-error) ### HTTP 503 [#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`. [Error](#schema-error) ## Schema: 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](#schema-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 [#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 [#schema-error] | Field | Required | Type | Meaning and constraints | | ------- | -------- | ------ | ----------------------- | | `error` | Yes | object | | ### `error` fields [#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](https://cherami.to/docs/api/errors) ยท [Download OpenAPI 3.1](https://cherami.to/openapi.json)