message.received event to your webhook subscriptions. Events are durable,
signed, and replayable.
Event types
Every delivery also names its type in the
X-Webhook-Event header.
Subscribe with POST /api/v1/webhook-subscriptions. Omit events to receive every type, or list each type you handle: a subscription receives only the types it lists.
Configuring a webhook
Two options:- Console: open Webhooks in the console sidebar, add your endpoint URL, and choose the event types.
- API: create a subscription with
POST /api/v1/webhook-subscriptions. See Webhook subscriptions.
signing_secret — rotate either without touching the other.
If you cannot expose a public URL during development, use the SSE stream or dev inbox instead.
Several API keys on one line
When your account has several API keys that accept new contacts on the same line, a first-time texter goes to the one key with an active webhook subscription. If none of them, or more than one, has an active subscription, the new contact goes to the key that sent a message most recently. Put the webhook subscription on the key that should own new contacts. A contact who already has a chat stays with the key that owns that chat.message.received envelope
Real-time, fires immediately when an inbound iMessage lands.
message.received
Field map
Compat note. Some legacy deliveries also include top-levelfrom,to,text,message_guid, andline_idaliases. New integrations should prefer thedata.*paths because they are richer and consistent across Chert-managed lines.
Receiving images and attachments
Inbound media is handled by the Chert API layer automatically. When a lead sends an image, recording, or file,data.message.parts[] carries an
attachment part. A fetchable part includes attachment_id; filename,
mime_type, and size_bytes are metadata hints and may be absent or generic.
Fetch the bytes with the same tenant auth you use for other API calls:
data.message.parts[] when reconstructing the message.
Receiving inbound voice memos
There is no separate inbound voice-note endpoint. An Apple voice memo arrives through the normalmessage.received workflow and is retrieved through the
same authenticated attachment-content route as other inbound media.
The following representative event reflects a verified case where the event
contained a generic MIME type and no filename:
message.received voice memo
The event may describe an inbound recording as
media or another
attachment-like part. Chert does not currently expose a universal provenance
flag that proves an audio attachment originated from Apple’s native voice
memo UI. Use attachment_id to retrieve it, then inspect the response and
bytes.Download with cURL
Bearer or HMAC authentication is required. For multi-tenant accounts, includex-chert-tenant; default single-tenant bearer requests may omit it.
--remote-header-name tells cURL to use the filename from
Content-Disposition. In the verified case, the response included headers
equivalent to:
Content-Type did not make the audio invalid. The downloaded
bytes were a playable CAF container with Opus audio.
Download with TypeScript
Download with Python
Inspect and convert the audio
Inspect the file signature and stream metadata instead of trusting only the webhook MIME type:caff) containing mono
Opus audio, approximately four seconds long at about 32 kbps. Apple inspection
reported 24 kHz Opus while FFmpeg exposed the decoded stream at 48 kHz. Do not
assume every Apple device or OS version produces this exact combination.
Convert CAF/Opus to a mono 16 kHz WAV for tools that do not accept the original
container or codec:
Replying
Two working paths. Pick by what you need:$CHAT_ID is data.chat.id from the webhook. $MESSAGE_GUID is message_guid (or data.message.id) and can be used for tapbacks with /messages/{id}/react. Use a normal chat follow-up for replies.
message.sent envelope
Fires once for each message sent through Chert, when your line reports it
sent. data.message.id is the message id from the send response; pass it to
GET /api/v1/messages/{id} for later status. delivered_at is set only when
delivery was already known, so this event does not confirm delivery.
message.sent
from, to, text, line_id, timestamp and message_guid
fields are legacy aliases. For a group message, to lists the recipients
separated by commas. Subscriptions on version 2026-11-16 do not receive
transport.
message.failed envelope
Fires when your line reports that a message failed after Chert accepted the
send. data.message.id is the same message id, and
GET /api/v1/messages/{id} records the failure. Not every failure produces this
event: a send that fails before it leaves your line returns an error to the send
request, and some lines report a failure only through
GET /api/v1/messages/{id}. Check the message status before you send again.
message.failed
Reactions (tapbacks)
When a contact adds or removes a tapback on a message in one of your chats, Chert deliversreaction.added or reaction.removed. Tapbacks your line sends
with POST /api/v1/messages/{id}/react are not delivered back to you.
reaction.added
A tapback in a group chat arrives on the group chat:
data.chat.id is the
group’s chat id, data.chat.is_group is true, data.chat.handles lists the
group’s members, and data.sender_handle is the member who reacted. Do not
look the sender up as a direct chat.
A tapback is not a reply. Most agents record it and do not answer it. Reaction
events do not count as a reply for the follow-up limit.
Headers
These headers are sent by Chert to your webhook endpoint during event delivery. Do not sendx-chert-tenant in your webhook receiver — that header is only for requests your application makes to Chert APIs.
Recommended webhook delivery headers
Legacy compatibility headers
Chert also emits these older lowercase headers for existing integrations. New integrations should read the recommendedX-Webhook-* headers above.
Both signature formats compute the same HMAC:
HMAC-SHA256(subscription_secret, "<ts>.<raw_body>").
Verifying the signature
Compute the HMAC over the raw request body (exact bytes as received) and compare with constant-time equality. Do not parse and re-serialize the JSON before verifying.401.
Retry behavior
Chert makes one live delivery attempt to each matching subscription as soon as the event is recorded, and waits up to 30 seconds for your response. Any2xx
response counts as delivered. Answer quickly and do slow work after you respond.
Retries stop after 8 attempts in total, counting the live attempt, or when the
event is 48 hours old, whichever comes first. The event then stays
failed and
its last recorded attempt says dead-letter. Replay it with
POST /api/v1/events/{id}/replay once your endpoint is fixed.
Disabled subscriptions
After 100 consecutive failed deliveries, Chert disables the subscription: it showsis_active: false and stops receiving live deliveries. While no other
active subscription takes that event type, the retry job probes the disabled
subscription with one of its still-retryable failed events on each run. One
successful delivery re-enables it and resets consecutive_failures to 0.
To re-enable it yourself, send PATCH /api/v1/webhook-subscriptions/{id} with
{"is_active": true}, which also resets the counter.
Events recorded while the subscription is disabled are marked failed and are
not retried. After you re-enable it, list them with
GET /api/v1/events?status=failed and replay each one.
At-least-once semantics
You may receive the same event more than once during retries, replays, or attachment-metadata repairs. Useevent_id (also exposed in the
X-Webhook-Event-Id header) to make side effects idempotent, but merge a
redelivery when it contains richer attachment or group metadata.
Replaying missed events
If your endpoint was down, list events withdelivery.status = failed and replay them:
?subscription_id=<subscription_id>.
See Events for the full debugging surface.
See also
Custom emoji reactions
Chert supports native custom emoji on enabled lines inreaction.added and
reaction.removed. Confirm custom-reaction support for the receiving line; an SDK version alone does not enable it.
Subscribe to both event names in /api/v1/webhook-subscriptions (an empty
events list already selects all events). Existing subscriptions are not changed.
The webhook envelope’s data.reaction contains the original reaction id,
target_message_id, applied_at, service, and this nested reaction value:
kind is emoji and emoji is absent;
Chert does not infer it from display text. The six standard reaction kinds are
unchanged. Sender identity remains in data.sender_handle.
To verify, send a message to an existing test chat with
POST /api/v1/chats/{id}/messages, add then remove 🔥 or 💥 from the recipient’s
Messages app, and query /api/v1/events?type=reaction.added and
/api/v1/events?type=reaction.removed. Each row’s payload contains the same
customer envelope. Check exact emoji, direction, target and sender, and confirm
your receiver gets both deliveries. The outbound /messages/{id}/react endpoint
still accepts only the six standard reactions. Previously stored events are not
rewritten; use new reactions for acceptance, not replay of a previously bad event.
Formatted inbound text
On formatting-enabled lines, text parts can includetext_decorations alongside
value. The same range shape is available in recorded history. Preserve the
plain text when styles are absent or your client cannot render them. See
Text formatting for UTF-16 range rules and preview scope.
