Webhooks

Webhooks let you receive HTTP POST callbacks for mailbox events. Configure delivery by creating one or more webhook subscriptions against the mailbox — 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.

Every event uses the same envelope. data.message carries the event's message payload. Two parallel peer-resolution lists ride alongside it:

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

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

Outbound example — message.sent

JSON

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.

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> }.
• 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. Matches are limited to records visible to the identity that owns the receiving mailbox. Contact visibility follows Contact access. Agent-identity visibility follows Agent visibility, with self-visibility (agents always match themselves).
• 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 visible 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. For identities, the endpoint is keyed by handle, not UUID: feed agent_identities[i].agent_handle into GET /api/v1/identities/{agent_handle} — see Manage identities.

Treat empty lists as "no matches," never as errors.

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

1. Have a mailbox provisioned (it's created atomically with its agent identity).
2. Create a subscription naming that mailbox, the HTTPS destination URL, and the subset of message.* event types you want delivered.

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

Request example

JSON

Code examples

cURL

cURL

JavaScript

Python

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

Inkbox signs every webhook payload with your organization's signing key. Create or rotate your key via the Signing Keys guide. Each webhook request includes three headers:

The signature input is constructed as:

{request_id}.{timestamp}.{raw_body}

Verification steps

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

Python verification example

Python

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