Webhooks
Webhooks let you receive HTTP POST callbacks the moment a connected human messages or tapbacks your agent, and as your agent's outbound messages move through their delivery lifecycle. iMessage events are delivered via the Webhook Subscriptions API — attach a subscription to the agent identity with the subset of imessage.* events you want.
The agent identity is the subscription owner (rather than a mailbox or phone number) because iMessage conversations ride a shared pool of lines that aren't org resources — the identity is the stable thing the events belong to.
Event types
| Event | Description |
|---|---|
imessage.received | A connected human sent your agent a message |
imessage.reaction_received | A connected human tapbacked one of the thread's messages |
imessage.sent | An outbound message from your agent was accepted for delivery |
imessage.delivered | An outbound message reached the recipient's device |
imessage.delivery_failed | An outbound message failed to deliver — the payload carries the error fields |
Inbound traffic rejected by a contact-rule block or by default-block in whitelist mode emits no webhooks. Blocked messages are stored, and admin API keys or the Inkbox Console can audit them with is_blocked=true. Fan-out also pauses while the identity is paused or has imessage_enabled: false. Tapback removals do not fire an event; the next message read simply no longer includes the removed tapback.
Subscribing
cURLSubscribe to any subset — add imessage.sent, imessage.delivered, and imessage.delivery_failed to the same subscription to track outbound delivery. See Webhook Subscriptions for listing, updating, and deleting subscriptions, and Signing keys for verifying that deliveries came from Inkbox.
Payload envelope
Every delivery POSTs a JSON envelope:
| Field | Type | Description |
|---|---|---|
event_type | string | One of the five imessage.* event types |
timestamp | string (ISO 8601) | When the event occurred |
data | object | The event payload — see below |
data carries exactly one of message (for imessage.received and the delivery-lifecycle events) or reaction (for imessage.reaction_received), plus peer-resolution lists:
| Field | Type | Description |
|---|---|---|
data.message | object | null | The stored message on imessage.received, imessage.sent, imessage.delivered, and imessage.delivery_failed; null on reaction events |
data.reaction | object | null | The stored reaction on imessage.reaction_received; null on message events |
data.contacts | array | Contact matches for the human's number, visible to the receiving identity. Always present, possibly empty — each entry has id and name |
data.agent_identities | array | Identity matches when the human's number belongs to another active agent identity in your org. Always present, possibly empty — each entry has id, agent_handle, and display_name |
imessage.received
JSONThe message shape matches the Message object, with one difference: webhook payloads carry no is_blocked field, because blocked messages never reach the webhook at all.
imessage.reaction_received
JSONreaction can be any of the classic six or "custom" with the literal emoji in custom_emoji. Remember the replacement rule: a new tapback from the same human on the same message replaces their previous one, so treat the latest event as the current state for that sender.
Delivery lifecycle events
Outbound messages fire an event on each message-level status transition: imessage.sent when the message is accepted for delivery, then imessage.delivered when it reaches the recipient's device, or imessage.delivery_failed if delivery fails. Only outbound messages produce these events, and only when the message as a whole changes status — per-recipient bookkeeping that doesn't move the message's own status does not fire.
The three payloads share one shape and differ only in event_type, the message's status, and the error fields:
JSONOn imessage.sent the message arrives with status: "sent", on imessage.delivered with status: "delivered", both with the error fields null. On imessage.delivery_failed the message's status is "declined" or "error" and the error fields describe what went wrong.
Delivery semantics
- Deliveries are fire-and-forget HTTP POSTs; your response status is logged but does not affect message processing. Respond
2xxquickly and process asynchronously. - Each subscription on the identity receives its own POST per event, independently.
- Verify deliveries with your signing key before trusting the payload.
