Webhooks

Webhooks let you receive HTTP POST callbacks for mailbox events. Configure delivery by creating one or more webhook subscriptions on the agent identity — each subscription names one HTTPS URL and the subset of message.* events you want delivered there. When an event fires, Inkbox sends a signed POST request to every subscription URL whose event_types list includes that event. The request includes headers you can use to verify the payload’s authenticity. message.received can include optional top-level Companion metadata. Handle its ordinary, initialization, and live phases before sender-based routing. An activation requires complete snapshot pagination and one combined initialization input; optional recent-message context is not a replacement. Received events include optional data.message.sender_access: "direct" when the message passed contact rules at receipt (including allowed by default), or "sponsored" when conversation sponsorship permits an originally default-filtered message. This is not sender trust or command permission. Unknown, system-generated, and outbound cases omit it. See per-message sender access.

Event types

Event	Description
`message.received`	An inbound email was ingested into the mailbox
`message.sent`	An outbound email was successfully sent. Does not fire for forwards.
`message.forwarded`	An outbound forward of a previously stored message via `POST /messages/{message_id}/forward`
`message.bounced`	An outbound email bounced or received a complaint
`message.failed`	An outbound email failed after exhausting all retry attempts
`message.delivered`	Delivery to the recipient’s mail server was confirmed

Payload shape

Every event uses the same envelope. Its id stays the same across retries and replays; use it to deduplicate events. data.message carries the message payload, including the owning mailbox’s email_address. Two peer-resolution lists accompany it:

data.contacts — address-book matches.
data.agent_identities — internal-agent matches (other agents in your organization that match a recipient).

On message.received, a subscription that configures conversation context also receives an additive data.context block; it is absent otherwise. Both lists are always present and possibly empty, never null. Each entry is tagged with the bucket (from / to / cc / bcc) it came from. A peer that’s both a contact and an internal agent appears once in each list. See Peer resolution below for the full pairing rules.

Inbound example — `message.received`

JSON

{
  "id": "evt_8f2c1a9b-7d6e-4f4a-b2c1-d0e94b21c377",
  "event_type": "message.received",
  "timestamp": "2026-04-10T18:13:42.201Z",
  "data": {
    "message": {
      "id": "d490b2a7-2ac8-4c57-bbdd-438c844e11d7",
      "mailbox_id": "73fdb447-4d3a-4a31-bf05-7373d6dfdf74",
      "email_address": "support@inkboxmail.com",
      "thread_id": "fef11c98-6f16-466b-b8d1-6019fc5b0183",
      "message_id": "<abc123@example.com>",
      "from_address": "customer@example.com",
      "to_addresses": ["support@inkboxmail.com"],
      "cc_addresses": ["legal@example.com"],
      "bcc_addresses": null,
      "subject": "Question about pricing",
      "snippet": "Can you help?",
      "body": "Can you help?",
      "body_state": "complete",
      "body_truncated": false,
      "body_total_chars": 13,
      "body_included_chars": 13,
      "direction": "inbound",
      "status": "received",
      "has_attachments": false,
      "created_at": "2026-04-10T18:13:42.104Z"
    },
    "contacts": [
      {
        "bucket": "from",
        "address": "customer@example.com",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe"
      },
      {
        "bucket": "cc",
        "address": "legal@example.com",
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Legal Team"
      }
    ],
    "agent_identities": []
  }
}

Outbound example — `message.sent`

JSON

{
  "id": "evt_7a6b1c9d-8e2f-4b3a-9c5d-0e1f2a3b4c5d",
  "event_type": "message.sent",
  "timestamp": "2026-04-10T18:15:03.287Z",
  "data": {
    "message": {
      "id": "d490b2a7-2ac8-4c57-bbdd-438c844e11d7",
      "mailbox_id": "73fdb447-4d3a-4a31-bf05-7373d6dfdf74",
      "email_address": "support@inkboxmail.com",
      "thread_id": "fef11c98-6f16-466b-b8d1-6019fc5b0183",
      "message_id": "<abc123@example.com>",
      "from_address": "support@inkboxmail.com",
      "to_addresses": ["customer@example.com"],
      "cc_addresses": ["legal@example.com"],
      "bcc_addresses": ["audit@inkboxmail.com"],
      "subject": "Re: Question about pricing",
      "snippet": "Absolutely. Here's the breakdown...",
      "body": null,
      "body_state": null,
      "body_truncated": null,
      "body_total_chars": null,
      "body_included_chars": null,
      "direction": "outbound",
      "status": "sent",
      "has_attachments": false,
      "created_at": "2026-04-10T18:15:03.221Z"
    },
    "contacts": [
      {
        "bucket": "to",
        "address": "customer@example.com",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe"
      },
      {
        "bucket": "cc",
        "address": "legal@example.com",
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Legal Team"
      },
      {
        "bucket": "bcc",
        "address": "audit@inkboxmail.com",
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Audit"
      }
    ],
    "agent_identities": [
      {
        "bucket": "cc",
        "address": "billing@inkboxmail.com",
        "id": "770e8400-e29b-41d4-a716-446655441000",
        "agent_handle": "billing",
        "display_name": "Billing"
      }
    ]
  }
}

Both data.contacts and data.agent_identities are always present on the wire and sparse — only matched recipients appear. An empty list means nothing matched. The same recipient can appear in both lists (when a peer is both a contact and an internal agent in your org); receivers decide precedence per row. data.message.bcc_addresses is symmetric with to_addresses and cc_addresses and is populated on outbound events only. Inbound payloads always carry "bcc_addresses": null, since BCC headers are not visible to recipients.

Message body

Inbound message.received events include a plain-text body when one is available. The body is limited to 16 KiB of UTF-8 text, with truncation at a complete character boundary.

Field	Type	Description
`data.message.body`	string \| null	Plain-text body, or its prefix when truncated.
`data.message.body_state`	string \| null	`complete`, `truncated`, or `unavailable` for inbound mail.
`data.message.body_truncated`	boolean \| null	Whether the supplied body is a prefix of the full text.
`data.message.body_total_chars`	integer \| null	Character count of the full text, or `null` when unavailable.
`data.message.body_included_chars`	integer \| null	Character count included in `body`, or `null` when unavailable.

These five fields are present as null on outbound and delivery-status events. A delivery notice received as message.received may also have all five fields set to null. For inbound mail without usable text, body_state is unavailable, body_truncated is false, and the body and character counts are null. When body_state is truncated or unavailable, get the message using data.message.email_address and data.message.id to retrieve its stored text and HTML parts.

Peer resolution

data.contacts and data.agent_identities are parallel lists of address-book and internal-agent matches respectively — one entry per matched recipient per list. Each entry is self-describing about which recipient bucket it pairs back to.

contacts entry shape: { "bucket": "from" | "to" | "cc" | "bcc", "address": <wire-form recipient>, "id": <uuid>, "name": <preferred name> | null }. name is null when the contact has no name on file. An automatically created contact uses the sender’s display name when provided, but never falls back to the email address, so check the field before addressing someone by name.
agent_identities entry shape: { "bucket": "from" | "to" | "cc" | "bcc", "address": <wire-form recipient>, "id": <uuid>, "agent_handle": <handle>, "display_name": <preferred name> | null }.
Match coverage per direction:
- Inbound (message.received) — from_address plus every entry of cc_addresses.
- Outbound (message.sent, message.delivered, message.forwarded, message.bounced, message.failed) — every entry of to_addresses, cc_addresses, and bcc_addresses.
Scope. Contact matches follow the receiving identity’s permissions. Profile controls whether a match is included; Memories can further hide memory text. Agent-identity matches include active identities in the same organization.
Pair on (bucket, address), not on address alone. The same address can appear in multiple buckets on a single send (e.g. the same recipient in both to_addresses and cc_addresses). When that happens, the matched entry appears twice in the list — once per bucket. Pairing on address alone produces phantom duplicates or attributes the match to the wrong recipient slot.
Intra-bucket dedupe. Duplicate addresses inside the same bucket collapse to a single entry. Case-only intra-bucket duplicates also collapse, with the first occurrence’s wire form preserved in address.
Address casing. address echoes the original wire form of the matched recipient — the same casing that appears in the corresponding data.message.{from_address|to_addresses|cc_addresses|bcc_addresses} field. Resolution itself runs against the lowercased canonical form, so receivers parsing arbitrary inbound mail may want to use a case-insensitive compare when pairing.
Sparse lists. Only matched recipients appear — there is no placeholder entry for unmatched recipients. "contacts": [] and "agent_identities": [] each mean nothing matched in that list.
Wire ordering. from → to → cc → bcc, and within each bucket the order matches the source field’s order (first occurrence wins on intra-bucket dedupe).
Per-event cap. Up to 50 distinct normalized addresses are resolved per event. Over-cap inputs and transient resolver failures fall back to empty lists; the message webhook itself still fires unchanged.
Tiebreak. If multiple contacts share the same email, the oldest by created_at wins. Receivers needing disambiguation can call GET /contacts/lookup. Agent-identity matches are 1:1 on the canonical email.
Hydration. Feed contacts[i].id into GET /api/v1/contacts/{contact_id} to fetch the full contact record — see Manage contacts. Agent-scoped credentials can discover peer identities through GET /api/v1/identities/a2a/directory; GET /api/v1/identities/{agent_handle} resolves only the caller’s own identity for those credentials.

Treat empty lists as “no matches,” never as errors.

Conversation context

When a subscription sets context_config, message.received payloads gain an additive data.context object keyed by the configured classes (email, texts, calls), so a handler can act on recent history without a follow-up API call. Delivery-status events never carry it. Each class is a block:

Field	Type	Description
`scope`	string	`thread` (the triggering mail thread), `conversation` (a texts conversation), or `contact` (cross-channel history resolved through the matched contact).
`mode`	string	`count` or `window`. Present only when the class returned items.
`requested`	integer	The configured `count` (count mode only).
`hours`	integer	The configured window (window mode only).
`items`	array	The history, oldest first, excluding the triggering item.
`truncated`	boolean	`true` if items were dropped to fit the 256 KB cap.
`skipped`	string	Present only on an empty block: `no_contact`, `no_resource`, or `unavailable`. A genuinely empty history is `items: []` with no `skipped`.

Item shapes by class:

email — id, direction, from_address, to_addresses, subject, snippet, created_at (metadata and snippet only; fetch full bodies via the messages API).
texts — id, channel (sms, imessage, or whatsapp, depending on the trigger), direction, sender, text (capped at 4,096 chars, with text_truncated), status, media, created_at.
calls — call_id, direction, remote_number, duration, started_at, abridged, and transcript. Each transcript entry is a turn (party, text, ts_ms, optional nullable phone_number) or, past 12,000 chars, an abridgment marker {"marker": "abridged", "omitted_turns": N, "omitted_ms": M} replacing the omitted middle — discriminate on marker. ts_ms is a capture timestamp in Unix epoch milliseconds; transcript line attribution explains phone_number.

For a whatsapp.received trigger from a non-group conversation, the texts block merges channel: "whatsapp" items from the triggering conversation with SMS and iMessage for the same remote number. A group whatsapp.received trigger includes only that group’s WhatsApp history, without SMS or iMessage. Mail, SMS, and iMessage triggers do not add WhatsApp history to their texts context. Nullable item-level fields are present as null, not omitted. Within call transcript turns, phone_number may be absent on older payloads or set to null; treat both as unavailable attribution. The whole block is capped at 256 KB; over the cap, the oldest items are dropped class by class (at least one per configured class survives) and that class’s truncated is set.

JSON

{
  "event_type": "message.received",
  "timestamp": "2026-04-10T18:13:42.201Z",
  "data": {
    "message": { "...": "as above" },
    "contacts": [],
    "agent_identities": [],
    "context": {
      "email": {
        "scope": "thread",
        "mode": "count",
        "requested": 10,
        "truncated": false,
        "items": [
          {
            "id": "0d3f7a52-9a1c-4a8e-b7f3-1c2d3e4f5a6b",
            "direction": "outbound",
            "from_address": "support@inkboxmail.com",
            "to_addresses": ["customer@example.com"],
            "subject": "Re: Question about pricing",
            "snippet": "Happy to walk you through it...",
            "created_at": "2026-04-09T16:02:11.000Z"
          }
        ]
      },
      "calls": {
        "scope": "contact",
        "items": [],
        "skipped": "no_contact"
      }
    }
  }
}

The full configuration shape and bounds live on the Webhook Subscriptions page.

Configuring webhooks

Mail webhook delivery is configured via the Webhook Subscriptions API. Two steps:

Choose an agent identity. You can subscribe before its mail channel is available.
Create a subscription naming that identity, the HTTPS destination URL, and the subset of message.* event types you want delivered.

You can attach up to 60 active subscriptions per identity — split events across URLs, or fan one URL out across many identities from many subscription rows. Creating a 61st returns 409; delete an existing one first.

Request example

JSON

{
  "agent_identity_id": "73fdb447-4d3a-4a31-bf05-7373d6dfdf74",
  "url": "https://yourapp.example.com/webhooks/inkbox",
  "event_types": ["message.received", "message.bounced"]
}

Code examples

curl -X POST "https://inkbox.ai/api/v1/webhooks/subscriptions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_identity_id": "73fdb447-4d3a-4a31-bf05-7373d6dfdf74",
    "url": "https://yourapp.example.com/webhooks/inkbox",
    "event_types": ["message.received", "message.bounced"]
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/webhooks/subscriptions",
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          agent_identity_id: identityId,
          url: "https://yourapp.example.com/webhooks/inkbox",
          event_types: ["message.received", "message.bounced"],
      }),
  }
);
const subscription = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/webhooks/subscriptions",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agent_identity_id": identity_id,
        "url": "https://yourapp.example.com/webhooks/inkbox",
        "event_types": ["message.received", "message.bounced"],
    },
)
subscription = response.json()

See Webhook Subscriptions for the full CRUD surface, validation rules, and per-route error codes.

Verifying webhook signatures

Inkbox signs every webhook payload with the agent identity’s signing key. Use the key of the identity that owns the subscription. Create or rotate a key via the Signing Keys guide. Each webhook request includes three signature headers:

Header	Description
`X-Inkbox-Request-ID`	Unique request identifier
`X-Inkbox-Timestamp`	Unix timestamp in seconds when the request was sent
`X-Inkbox-Signature`	`sha256=<hex_digest>` — HMAC-SHA256 of the signed content

When the subscription sets an auth_token, each request additionally carries Authorization: Bearer <token> — the bearer token authenticates Inkbox to your endpoint, while the signature headers prove the payload. See Authenticating to your endpoint. The signature input is constructed as:

{request_id}.{timestamp}.{raw_body}

Verification steps

Check the timestamp — reject the request if X-Inkbox-Timestamp is more than 300 seconds from the current time.
Reconstruct the message — concatenate {X-Inkbox-Request-ID}.{X-Inkbox-Timestamp}.{raw_body}.
Compute the HMAC — use HMAC-SHA256 with your signing key over the reconstructed message.
Compare digests — the resulting hex digest should match the value after sha256= in the X-Inkbox-Signature header.

Python verification example

Python

import hashlib
import hmac
import time

def verify_webhook(
    raw_body: bytes,
    request_id: str,
    timestamp: str,
    signature: str,
    signing_key: str,
    tolerance_seconds: int = 300,
) -> bool:
    # 1. Check timestamp freshness
    ts = int(timestamp)
    if abs(time.time() - ts) > tolerance_seconds:
        return False

    # 2. Reconstruct the signed message
    message = f"{request_id}.{timestamp}.{raw_body.decode()}"

    # 3. Compute HMAC-SHA256
    expected = hmac.new(
        signing_key.encode(),
        message.encode(),
        hashlib.sha256,
    ).hexdigest()

    # 4. Compare with provided signature
    provided = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, provided)

Disabling webhooks

To stop receiving webhooks at a URL, delete the subscription that owns it. Delivery stops immediately.

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

WhatsApp API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Event types

Payload shape

Inbound example — `message.received`

Outbound example — `message.sent`

Message body

Peer resolution

Conversation context

Configuring webhooks

Request example

Code examples

Verifying webhook signatures

Verification steps

Python verification example

Disabling webhooks

​Event types

​Payload shape

​Inbound example — message.received

​Outbound example — message.sent

​Message body

​Peer resolution

​Conversation context

​Configuring webhooks

​Request example

​Code examples

​Verifying webhook signatures

​Verification steps

​Python verification example

​Disabling webhooks

Event types

Payload shape

Inbound example — `message.received`

Outbound example — `message.sent`

Message body

Peer resolution

Conversation context

Configuring webhooks

Request example

Code examples

Verifying webhook signatures

Verification steps

Python verification example

Disabling webhooks