webhooks

Add a webhook

Adds a webhook: an HTTPS URL that receives one or both event types, for every inbox on the account (including ones created later) or for up to 10 listed inboxes. The 201 response includes the signing secret; after that it appears only when you retrieve it.

  • message.received: a received message is ready to read.
  • message.sent: the provider accepted a sent message. This is not delivery.

A delivery carries identifiers only (id, type, timestamp, data.inbox_id, data.message_id): fetch the message through the API, and deduplicate on id. Verify the signature on the raw body and answer with a 2xx within 15 seconds once you've stored the event: see Verify and acknowledge.

If the response is lost, list webhooks, find the URL and retrieve its secret rather than adding it again.

post/v1/webhooks

Request

  • Base URL: https://cherami.to
  • URL: https://cherami.to/v1/webhooks
  • Auth: HTTP bearer

Request body

urlstring required

HTTPS URL on a public host, without credentials or a fragment; at most 2048 characters. It can't be changed later: to move it, add a new webhook and delete this one.

event_typesWebhookEventType[] required
inbox_idsstring[]

Up to 10 of the account's live inboxes. Empty or omitted means every inbox, including ones created later.

Response

Created.

idstring required

Cherami resource ID.

created_atstring date-time required

UTC timestamp with milliseconds.

urlstring nullable required

Destination URL; null while status is pending or unknown.

event_typesWebhookEventType[] nullable required
inbox_idsstring[] nullable required

Scoped inboxes; empty means every inbox.

deleted_inbox_idsstring[] required

Scoped inboxes that have since been deleted. They match nothing; edit inbox_ids to remove them.

enabledboolean nullable required
updated_atstring date-time nullable required

UTC timestamp with milliseconds.

status'active' | 'disabled' | 'pending' | 'unknown' required
secret_rotated_atstring date-time nullable required

UTC timestamp with milliseconds.

previous_secret_expires_atstring date-time nullable required

UTC timestamp with milliseconds.

secretstring required

Signing secret for Standard Webhooks verification (whsec_...). Returned only on creation, retrieval and rotation.

Changes

No recorded changes to this operation across all 1 revision of this API.