Payload Format

When an event fires, your endpoint receives an HTTP POST request with Content-Type: application/json and this JSON body.

Event Payload

All webhook deliveries follow this structure.

POST payload

{
  "event": "email.received",
  "timestamp": "2026-02-07T12:00:00Z",
  "webhook_id": "<webhook-uuid>",
  "agent_id": "<agent-uuid>",
  "email_account_id": "<account-uuid>",
  "email": {
    "id": "<email-uuid>",
    "message_id": "<message-id@xobni.ai>",
    "thread_id": "<thread-uuid>",
    "direction": "inbound",
    "from_address": "sender@example.com",
    "is_trusted_sender": true,
    "trusted_sender_name": "John Smith",
    "to_addresses": ["agent@xobni.ai"],
    "cc_addresses": [],
    "subject": "Hello from a customer",
    "snippet": "First 200 characters of the email body...",
    "status": "received",
    "has_attachments": true,
    "attachment_count": 2,
    "received_at": "2026-02-07T12:00:00Z"
  }
}

Payloads are lightweight — they include email metadata and a 200-character snippet, not the full body. Use the read_email API or MCP tool to fetch full content when needed.

Payload Fields

Top-level fields

eventEvent type: "email.received", "email.sent", or "test"

timestampISO 8601 timestamp of when the event occurred

webhook_idUUID of the webhook that triggered this delivery

agent_idUUID of the agent

email_account_idUUID of the email account

email object

idUUID of the email

message_idRFC 5322 Message-ID header

thread_idUUID of the thread (if threaded)

direction"inbound" or "outbound"

from_addressSender email address

is_trusted_senderWhether the sender is on the trusted senders list

trusted_sender_nameDisplay name of the trusted sender (null if not trusted)

to_addressesArray of recipient addresses

subjectEmail subject line

snippetFirst 200 characters of body text

has_attachmentsBoolean indicating if attachments exist

attachment_countNumber of attachments

Setup Verification