Skip to main content
When a lead replies from either a phone number or Apple ID email handle, Chert creates or matches the tenant-scoped chat and delivers a real-time 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. Event lifecycle

Configuring a webhook

Two options:
  1. Console: open Webhooks in the console sidebar, add your endpoint URL, and choose the event types.
  2. API: create a subscription with POST /api/v1/webhook-subscriptions. See Webhook subscriptions.
The webhook subscription secret is independent from your API 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-level from, to, text, message_guid, and line_id aliases. New integrations should prefer the data.* 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:
The attachment id is tenant-scoped. If an inbound contains both text and media, keep the array order from 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 normal message.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, include x-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:
The generic 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:
One verified sample was Apple CAF/Core Audio Format (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:
Chert preserves the downloaded recording; it does not automatically convert inbound audio to MP3 or WAV. No transcript field is currently returned, and Chert does not perform automatic speech-to-text or semantic interpretation. Applications that need a transcript must send the downloaded audio to their chosen speech-to-text system.

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
The top-level 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 delivers reaction.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 send x-chert-tenant in your webhook receiver — that header is only for requests your application makes to Chert APIs.

Legacy compatibility headers

Chert also emits these older lowercase headers for existing integrations. New integrations should read the recommended X-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.
Reject any request that fails verification with 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. Any 2xx 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 shows is_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. Use event_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 with delivery.status = failed and replay them:
To replay to one subscription instead of every matching active subscription, add ?subscription_id=<subscription_id>. See Events for the full debugging surface.

See also

Custom emoji reactions

Chert supports native custom emoji on enabled lines in reaction.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:
The emoji is the exact observed Unicode sequence, including skin tones and ZWJ sequences. If an older worker omitted it, or the value carried control or bidirectional formatting characters, 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 include text_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.