Webhooks

Enable the mailbox’s Webhook toggle in the Delivery section, then fill in the Webhook section of the mailbox editor: the URL, an Authentication mode (NONE, BEARER TOKEN, or CUSTOM HEADER — it writes the header for you), and, under Advanced, the raw headers JSON, body template, and signing secret. Every completed extraction is POSTed to your URL as JSON. Delivery is optional: with both delivery toggles off (the default), results stay in the inbox and you download them per item — no webhook setup needed.

Requirements

The URL must be a public HTTPS URL. Plain HTTP, localhost, and private network addresses are rejected.
Your endpoint must respond with a 2xx status within 10 seconds.

Payload

{
  "id": "em_01JAB7Q2M3N4P5Q6R7S8T9V0W1",
  "mailbox": "inv-7k2f@in.bouncebox.app",
  "received_at": "2026-09-16T10:24:03.512Z",
  "from": "billing@acmesupplies.com",
  "subject": "Invoice INV-2041 from Acme Supplies",
  "schema_template": "invoice",
  "attachments": [
    {
      "filename": "inv-2041.pdf",
      "contentType": "application/pdf",
      "size": 81234,
      "url": "https://signed-download.example/inv-2041.pdf"
    }
  ],
  "data": {
    "invoice_number": "INV-2041",
    "amount_total": 1190.0,
    "currency": "EUR"
  }
}

data is the extracted result — exactly what the EXTRACTED RESULT panel shows.
attachments[].url is a signed download link valid for 7 days, or null if the file can’t be shared. Download eagerly; don’t store the link.

Headers

Every POST includes:

Header	Value
`Content-Type`	`application/json`
`X-BounceBox-Signature`	`sha256=<hex>` — HMAC-SHA256 of the exact raw body, keyed with the signing secret
(your headers)	Headers from the Authentication picker, or the raw Headers (JSON object) under Advanced

Verifying the signature

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== "string") return false;
  const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
  return (
    expected.length === signatureHeader.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
  );
}

The signature is computed over the exact raw body — verify it before you parse the JSON. The signing secret is the built-in default unless the mailbox sets its own under Advanced · Signing secret. The mailbox editor’s Verify signatures block shows the same snippet prefilled with that mailbox’s secret, and its Last delivery line reports the most recent attempt’s status and HTTP code.

Check X-BounceBox-Signature over the raw request body before parsing and acting on the payload, and reject mismatches with a non-2xx status. The signature proves the request is authentic and untampered, but it does not prevent replays — the payload carries no timestamp. Protect your endpoint by tracking payload IDs and ignoring duplicates.

Custom body template

Leave Body template empty to get the canonical payload above. To send a custom shape, write a template using placeholders — click the + button next to the field to insert one at the cursor:

{{mailbox}}, {{received_at}}, {{email_id}}, {{from}}, {{subject}} — email metadata
{{attachments}} — the attachment list
{{data}} — the extracted JSON
{{data.<field>}} — a single extracted field, e.g. {{data.invoice_number}}

Missing fields render as empty strings.

Testing your endpoint

Click Send test webhook in the mailbox editor (web and mobile app) to POST a signed sample payload to the URL currently in the form — unsaved changes included. The response status appears inline, so you can verify your endpoint accepts the payload shape and signature before saving. The MCP server exposes the same check as the test_webhook tool.

Retries

Up to 4 attempts per webhook delivery.
A 2xx within 10 seconds is success. Anything else — a 5xx, a timeout, or a network error — is retried with a growing backoff: about 1s, 4s, 9s, 16s.
A 4xx response fails delivery immediately without retry — a rejected request won’t get better by waiting.

Every attempt lands in the mailbox’s delivery log. For order mailboxes, see Order emails for sender allowlists and the review fields the webhook payload carries.

Getting started

Dashboard guide

Configuration

Integrations

Billing

Help

Requirements

Payload

Headers

Verifying the signature

Custom body template

Testing your endpoint

Retries

​Requirements

​Payload

​Headers

​Verifying the signature

​Custom body template

​Testing your endpoint

​Retries

Requirements

Payload

Headers

Verifying the signature

Custom body template

Testing your endpoint

Retries