Webhook Event Catalog

Wirebox triggers webhooks in real time whenever activity occurs across your communication channels. Every delivery is signed with HMAC-SHA256 — see Signature Verification.

Envelope

All events share the same envelope. The event-specific object lives under data:

{
  "id": "evt_01J8ABC123",
  "event_type": "email.received",
  "timestamp": "2026-09-11T12:00:00Z",
  "data": { }
}

Field	Type	Description
`id`	string	Unique, stable event ID (`evt_` prefix). Reuse it to deduplicate deliveries.
`event_type`	string	Event name (see below).
`timestamp`	string	ISO 8601 time the event was dispatched.
`data`	object	Event-specific payload.

Email Events

`email.received`

Triggered when an incoming email arrives at an agent’s inbox. Emails rejected by the agent’s inbound guardrails are quarantined and never dispatched.

{
  "id": "evt_01J8ABC123",
  "event_type": "email.received",
  "timestamp": "2026-09-11T12:00:00Z",
  "data": {
    "message": {
      "id": "msg_01J8DEF456",
      "mailbox_address": "eva@wireboxmail.com",
      "agent_handle": "eva",
      "thread_id": "thrd_01J8GHI789",
      "from": "Alex Customer <alex@example.com>",
      "to": ["eva@wireboxmail.com"],
      "cc": [],
      "subject": "Need help with integration",
      "snippet": "Hello, how do I connect my agent?",
      "sender_access": "default_allowed",
      "created_at": "2026-09-11T12:00:00Z"
    }
  }
}

sender_access reflects how the inbound guardrails classified the sender: direct (exact rule), reply_thread (continuing an outbound thread), or default_allowed (baseline posture).

`email.sent`

Triggered when an outbound email (send, reply, or forward) is accepted by Wirebox for delivery.

{
  "id": "evt_01J8ABC124",
  "event_type": "email.sent",
  "timestamp": "2026-09-11T12:01:00Z",
  "data": {
    "message": {
      "id": "msg_01J8OUTBOUND789",
      "mailbox_address": "eva@wireboxmail.com",
      "thread_id": "thrd_01J8GHI789",
      "from": "Eva Customer Support <eva@wireboxmail.com>",
      "to": ["alex@example.com"],
      "cc": [],
      "subject": "Re: Need help with integration",
      "snippet": "Happy to help — here is how to connect your agent.",
      "created_at": "2026-09-11T12:01:00Z"
    }
  }
}

`email.delivered`

Triggered when an outbound email has been successfully delivered and accepted by the recipient’s mail server (SMTP 250 OK handshake).

{
  "id": "evt_01J8ABC125",
  "event_type": "email.delivered",
  "timestamp": "2026-09-11T12:02:45Z",
  "data": {
    "message": {
      "id": "msg_01J8OUTBOUND789",
      "mailbox_address": "eva@wireboxmail.com",
      "agent_handle": "eva",
      "thread_id": "thrd_01J8GHI789",
      "from": "eva@wireboxmail.com",
      "to": ["alex@example.com"],
      "subject": "Re: Need help with integration"
    },
    "delivery": {
      "recipient": "alex@example.com",
      "smtp_response": "250 2.0.0 OK: message queued 123456789",
      "timestamp": "2026-09-11T12:02:45Z"
    }
  }
}

`email.bounced`

Triggered when an outbound email cannot be delivered and receives a bounce notification or rejection from the remote mail server (such as an invalid address, full mailbox, or SPF/DKIM/DMARC policy failure).

{
  "id": "evt_01J8ABC126",
  "event_type": "email.bounced",
  "timestamp": "2026-09-11T12:03:10Z",
  "data": {
    "message": {
      "id": "msg_01J8OUTBOUND789",
      "mailbox_address": "eva@wireboxmail.com",
      "agent_handle": "eva",
      "thread_id": "thrd_01J8GHI789",
      "from": "eva@wireboxmail.com",
      "to": ["nonexistent@example.com"],
      "subject": "Proposal for your review"
    },
    "bounce": {
      "recipient": "nonexistent@example.com",
      "bounce_type": "hard",
      "reason": "550 5.1.1 <nonexistent@example.com>: Recipient address rejected: User unknown",
      "diagnostic_code": "smtp; 550-5.1.1 The email account that you tried to reach does not exist."
    }
  }
}

Field	Type	Description
`bounce.recipient`	string	The specific recipient address that bounced.
`bounce.bounce_type`	string	`"hard"` (permanent error, e.g. mailbox not found) or `"soft"` (temporary failure, e.g. mailbox full).
`bounce.reason`	string	Rejection summary from the remote mail server.
`bounce.diagnostic_code`	string \| null	Verbatim SMTP diagnostic response code.

`email.failed`

Triggered when an outbound email fails permanently due to system transport errors, invalid credentials, or exhausted retries.

{
  "id": "evt_01J8ABC127",
  "event_type": "email.failed",
  "timestamp": "2026-09-11T12:03:30Z",
  "data": {
    "message": {
      "id": "msg_01J8OUTBOUND789",
      "mailbox_address": "eva@wireboxmail.com",
      "agent_handle": "eva",
      "thread_id": "thrd_01J8GHI789",
      "from": "eva@wireboxmail.com",
      "to": ["client@example.com"],
      "subject": "Proposal for your review"
    },
    "failure": {
      "recipient": "client@example.com",
      "error": "Upstream SMTP connection timeout",
      "timestamp": "2026-09-11T12:03:30Z"
    }
  }
}

SMS Events

`sms.received`

Triggered immediately when an incoming SMS or MMS arrives on an agent’s phone number.

{
  "id": "evt_01J8ABC140",
  "event_type": "sms.received",
  "timestamp": "2026-09-18T02:15:00Z",
  "data": {
    "message": {
      "id": "msg_01J8DEF111",
      "channel": "sms",
      "phone_number": "+14232190980",
      "agent_handle": "sale-mark",
      "direction": "inbound",
      "type": "sms",
      "from_number": "+15551234567",
      "to_numbers": ["+14232190980"],
      "text": "Your verification code is 482910",
      "media": null,
      "has_media": false,
      "segments": 1,
      "created_at": "2026-09-18T02:15:00Z"
    }
  }
}

iMessage Events

`imessage.connected`

Triggered when a human user connects to an agent via the router line (texting connect @agent or scanning the QR code).

{
  "id": "evt_01J8ABC131",
  "event_type": "imessage.connected",
  "timestamp": "2026-09-17T10:28:00Z",
  "data": {
    "conversation_id": "conv_01J8ABC123XYZ",
    "identity_id": "ident_01J8ABC123XYZ",
    "agent_handle": "eva",
    "user_phone": "+15551234567",
    "connected_at": "2026-09-17T10:28:00Z"
  }
}

`imessage.disconnected`

Triggered when an active iMessage conversation session is disconnected.

{
  "id": "evt_01J8ABC132",
  "event_type": "imessage.disconnected",
  "timestamp": "2026-09-17T11:00:00Z",
  "data": {
    "conversation_id": "conv_01J8ABC123XYZ",
    "identity_id": "ident_01J8ABC123XYZ",
    "user_phone": "+15551234567",
    "status": "disconnected",
    "disconnected_at": "2026-09-17T11:00:00Z"
  }
}

`imessage.received`

Triggered when an inbound blue bubble arrives from a user. The connection handshake itself is also delivered with is_handshake: true.

{
  "id": "evt_01J8ABC127",
  "event_type": "imessage.received",
  "timestamp": "2026-09-17T10:30:00Z",
  "data": {
    "id": "msg_01J8DEF456GHI",
    "conversation_id": "conv_01J8ABC123XYZ",
    "identity_id": "ident_01J8ABC123XYZ",
    "direction": "inbound",
    "sender": "+15551234567",
    "text": "Hello Eva, can you summarize my tasks today?",
    "media_url": null,
    "created_at": "2026-09-17T10:30:00Z"
  }
}

`imessage.sent`

Triggered when an outbound iMessage is accepted by the gateway.

{
  "id": "evt_01J8ABC128",
  "event_type": "imessage.sent",
  "timestamp": "2026-09-17T10:30:05Z",
  "data": {
    "id": "msg_01J8DEF456GHJ",
    "conversation_id": "conv_01J8ABC123XYZ",
    "identity_id": "ident_01J8ABC123XYZ",
    "direction": "outbound",
    "to": "+15551234567",
    "text": "You have 3 tasks scheduled for today.",
    "media_url": null,
    "status": "sent",
    "error": null,
    "created_at": "2026-09-17T10:30:05Z"
  }
}

`imessage.failed`

Triggered when an outbound iMessage send fails. The payload matches imessage.sent with status set to the failure state and error populated.

{
  "id": "evt_01J8ABC130",
  "event_type": "imessage.failed",
  "timestamp": "2026-09-17T10:30:10Z",
  "data": {
    "id": "msg_01J8DEF456GHJ",
    "conversation_id": "conv_01J8ABC123XYZ",
    "identity_id": "ident_01J8ABC123XYZ",
    "direction": "outbound",
    "to": "+15551234567",
    "text": "You have 3 tasks scheduled for today.",
    "media_url": null,
    "status": "failed",
    "error": "Recipient is not registered with Apple iMessage",
    "created_at": "2026-09-17T10:30:10Z"
  }
}

System Events

`test.ping`

Diagnostic event sent only to the webhook being tested, via Send Test Ping or the Console.

{
  "id": "evt_01J8TEST999",
  "event_type": "test.ping",
  "timestamp": "2026-09-11T12:00:00Z",
  "data": {
    "ping": "pong",
    "message": "This is a live test webhook notification from Wirebox.",
    "triggered_at": "2026-09-11T12:00:00Z"
  }
}

A2A Events

Agent-to-Agent (A2A) events notify your backend systems of incoming assignments, multi-turn dialogue, progress markers, and task state transitions.

`a2a.task.created`

Triggered when a caller agent submits a new task to an agent identity via JSON-RPC SendMessage. Used to awaken the worker agent’s execution runtime.

{
  "id": "evt_01J8ABC201",
  "event_type": "a2a.task.created",
  "timestamp": "2026-10-20T12:00:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "context_id": "ctx_01J8DEF456",
    "state": "submitted",
    "initial_message": {
      "role": "user",
      "parts": [{ "text": "Please summarize our Q3 user feedback trends." }],
      "created_at": "2026-10-20T12:00:00Z"
    },
    "requester": {
      "handle": "coordinator-bot",
      "source": "a2a_rpc"
    }
  }
}

`a2a.task.updated`

Triggered whenever a message is appended to an ongoing task, metadata is updated, or a worker reply is posted.

{
  "id": "evt_01J8ABC202",
  "event_type": "a2a.task.updated",
  "timestamp": "2026-10-20T12:01:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "state": "working",
    "status_message": "Synthesizing recommendations",
    "artifacts_count": 0,
    "latest_message": {
      "role": "agent",
      "parts": [{ "text": "Analyzed 1,420 feedback records." }],
      "created_at": "2026-10-20T12:01:00Z"
    }
  }
}

`a2a.task.progress`

Triggered when a worker submits an intermediate progress report (intent: "progress").

{
  "id": "evt_01J8ABC203",
  "event_type": "a2a.task.progress",
  "timestamp": "2026-10-20T12:02:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "state": "working",
    "intent": "progress",
    "status_message": "Scanning ticket sentiment",
    "artifacts_count": 0,
    "latest_message": {
      "role": "agent",
      "parts": [{ "text": "Batch 2 of 5 complete." }]
    }
  }
}

`a2a.task.input_required`

Triggered when a worker suspends execution to request caller clarification or missing parameters (intent: "ask_caller").

{
  "id": "evt_01J8ABC204",
  "event_type": "a2a.task.input_required",
  "timestamp": "2026-10-20T12:03:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "state": "input_required",
    "intent": "ask_caller",
    "status_message": "Waiting for caller clarification",
    "artifacts_count": 0,
    "latest_message": {
      "role": "agent",
      "parts": [{ "text": "Should the report include EMEA region data?" }]
    }
  }
}

`a2a.task.completed`

Triggered when a worker completes the job and delivers final artifacts (intent: "complete").

{
  "id": "evt_01J8ABC205",
  "event_type": "a2a.task.completed",
  "timestamp": "2026-10-20T12:05:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "state": "completed",
    "intent": "complete",
    "status_message": "Report generated successfully",
    "artifacts_count": 1,
    "latest_message": {
      "role": "agent",
      "parts": [{ "text": "Executive summary generated successfully." }]
    }
  }
}

`a2a.task.failed`

Triggered when a worker encounters an unrecoverable failure and marks the task failed (intent: "fail").

{
  "id": "evt_01J8ABC206",
  "event_type": "a2a.task.failed",
  "timestamp": "2026-10-20T12:06:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "state": "failed",
    "intent": "fail",
    "status_message": "Data source connection timeout",
    "artifacts_count": 0,
    "latest_message": {
      "role": "agent",
      "parts": [{ "text": "Could not connect to external CRM database." }]
    }
  }
}

`a2a.task.canceled`

Triggered when the requester cancels a task before completion via JSON-RPC CancelTask.

{
  "id": "evt_01J8ABC207",
  "event_type": "a2a.task.canceled",
  "timestamp": "2026-10-20T12:07:00Z",
  "data": {
    "task_id": "task_01J8ABC123XYZ",
    "agent_handle": "eva",
    "reason": "Duplicate request"
  }
}

Overview

Vault

Agent Identities

Mail

Domains

Phone

iMessage

Tunnel

Webhooks

Agent-to-Agent (A2A)

Webhook Event Catalog

Envelope

Email Events

`email.received`

`email.sent`

`email.delivered`

`email.bounced`

`email.failed`

SMS Events

`sms.received`

iMessage Events

`imessage.connected`

`imessage.disconnected`

`imessage.received`

`imessage.sent`

`imessage.failed`

System Events

`test.ping`

A2A Events

`a2a.task.created`

`a2a.task.updated`

`a2a.task.progress`

`a2a.task.input_required`

`a2a.task.completed`

`a2a.task.failed`

`a2a.task.canceled`

​Envelope

​Email Events

​email.received

​email.sent

​email.delivered

​email.bounced

​email.failed

​SMS Events

​sms.received

​iMessage Events

​imessage.connected

​imessage.disconnected

​imessage.received

​imessage.sent

​imessage.failed

​System Events

​test.ping

​A2A Events

​a2a.task.created

​a2a.task.updated

​a2a.task.progress

​a2a.task.input_required

​a2a.task.completed

​a2a.task.failed

​a2a.task.canceled

Envelope

Email Events

`email.received`

`email.sent`

`email.delivered`

`email.bounced`

`email.failed`

SMS Events

`sms.received`

iMessage Events

`imessage.connected`

`imessage.disconnected`

`imessage.received`

`imessage.sent`

`imessage.failed`

System Events

`test.ping`

A2A Events

`a2a.task.created`

`a2a.task.updated`

`a2a.task.progress`

`a2a.task.input_required`

`a2a.task.completed`

`a2a.task.failed`

`a2a.task.canceled`