Jump to

Webhooks

Webhooks let you receive HTTP POST callbacks for mailbox events. Configure a webhook URL on your mailbox via PATCH /mailboxes/{email_address} — no separate webhook CRUD is needed.

When an event fires, Inkbox sends a signed POST request to your URL. The request includes headers you can use to verify the payload's authenticity.

Event types

Event	Description
`message.received`	An inbound email was ingested into the mailbox
`message.sent`	An outbound email was successfully sent via SES
`message.bounced`	An outbound email bounced or received a complaint
`message.failed`	An outbound email failed after exhausting all retry attempts
`message.delivered`	SES confirmed delivery to the recipient's mail server

Configuring webhooks PATCH

PATCH /mailboxes/{email_address}

Set the webhook_url field on a mailbox to start receiving event callbacks at that URL. All event types are delivered to the configured URL.

Request example

JSON

Code examples

Verifying webhook signatures

Inkbox signs every webhook payload with your organization's signing key. Create or rotate your key via the Signing Keys API. Each webhook request includes three 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

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

Disabling webhooks PATCH

To stop receiving webhooks, set webhook_url to null via the same PATCH endpoint:

JSON