Add a webhook

POST /v1/webhooks

Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.

Adds a webhook: a destination URL subscribed to one or both event types, for every inbox of the account (including inboxes created later) or for at most 10 named inboxes. Returns 201 with the webhook and its secret; this response and explicit retrieval are the only places the secret appears.

message.received fires when received mail becomes ready to read. message.sent fires when the provider's acceptance of an outgoing message is persisted, which is not delivery. Payloads carry identifiers only (id, type, timestamp, data.inbox_id, data.message_id); fetch content through the authenticated API and deduplicate on the payload id.

The URL is validated for shape (https, public hostname, no credentials or fragment) and is not fetched by Cherami; the delivery provider refuses private or unroutable destinations at delivery time. There is no URL edit: add a new webhook and delete the old one.

No creation key exists. If the response is lost, list webhooks, match the URL and retrieve the secret explicitly; do not add again. A 503 webhook_creation_uncertain names a pending webhook ID to delete before retrying. Verify signatures on the raw body and acknowledge with a 2xx within 15 seconds once you have durably accepted the event: see Receive webhook notifications.

Request bodyCopy Anchor Link

JSON object. Total UTF-8 request body limit: 4096 bytes.

Schema: CreateWebhookCopy Anchor Link

There is no URL edit: to change the destination, add a webhook and delete the old one.

Unknown fields are rejected.

curl exampleCopy Anchor Link

Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.

Save the intended payload as a private request.json file and replace illustrative values. For an uncertain response, follow the operation-specific recovery rules.

{
  "url": "https://example.com/hooks/cherami",
  "event_types": [
    "message.received"
  ],
  "inbox_ids": [
    "22222222-2222-4222-8222-222222222222"
  ]
}

curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/webhooks" \
  --header "Authorization: Bearer $CHERAMI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

ResponsesCopy Anchor Link

HTTP 201Copy Anchor Link

Successful operation; inspect resource state and outcome fields.

• X-Request-ID: Support correlation ID, not an idempotency key.
• Location: Relative URL of the resulting resource.

Content type: application/json.

CreatedWebhook

{
  "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,
  "secret": "whsec_EXAMPLE_NOT_A_REAL_SECRET"
}

HTTP 400Copy Anchor Link

invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.

invalid_webhook: Use only url, event_types and inbox_ids when adding a webhook.

invalid_webhook_url: Use an https URL with a public hostname, without credentials or a fragment. The provider also rejects private or unroutable destinations.

invalid_webhook_event_types: Supply a nonempty array containing message.received and/or message.sent.

invalid_webhook_inbox_ids: Supply inbox_ids as an array of at most 10 inbox IDs, or an empty array for every inbox.

unknown_webhook_inbox: Every inbox_id must be a live inbox of this account. error.details.inbox_ids lists the rejected IDs.

• X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 401Copy Anchor Link

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.

Error

HTTP 413Copy Anchor Link

body_too_large: Reduce the JSON request to the endpoint's body limit.

• X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 415Copy Anchor Link

unsupported_media_type: Send Content-Type: application/json.

• X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 503Copy Anchor Link

webhook_provider_unavailable: The webhook provider refused or could not take the request and nothing was applied. Retry later.

webhook_creation_uncertain: The provider did not confirm the new webhook. error.details.webhook_id is listed as pending: delete it and add again rather than adding a duplicate.

webhook_secret_unavailable: The signing secret could not be read. If error.details.webhook_id is present the webhook was added; retrieve its secret explicitly.

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: CreatedWebhookCopy Anchor Link

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.

Schema: WebhookEventTypeCopy Anchor Link

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: ErrorCopy Anchor Link

error fieldsCopy Anchor Link

HTTP conventions, errors and pagination · Download OpenAPI 3.1