Webhook payload reference

Use this hub to find the right payload contract for a MailWebhook route.

MailWebhook sends the route pipeline output as the HTTP request body. No extra wrapper is added around the mapper output. Delivery headers such as X-MailWebhook-Signature and X-Idempotency-Key are part of the HTTP request, not fields inside the JSON payload.

For product context around structured email data, see Email to JSON. If you are building a receiving endpoint, see Email Webhook API.

Table of contents

  1. Payload selection
  2. HTTP request body contract
  3. Generic JSON
  4. Custom JSON
  5. Transform steps before mapping
  6. Attachment descriptors
  7. Delivery metadata and headers
  8. Quick validation checklist
  9. Related docs

Payload selection

Choose the payload based on what the downstream system expects.

Payload typePipeline mapperUse whenReference
Generic JSONmap.generic_jsonYou want MailWebhook’s stable normalized email shape.Generic JSON
Custom JSONmap.custom_jsonYou need route-specific fields or a downstream-specific body shape.Custom JSON
Slack simplemap.slack_simpleYou want a short Slack-compatible message body.Pipeline
Telegram simplemap.telegram_simpleYou want a short Telegram-compatible message body.Pipeline

Most webhook integrations should start with map.generic_json. Move to map.custom_json when the receiver needs a smaller or different shape.

HTTP request body contract

Every route pipeline follows the same delivery rule:

  • The final map.* step creates the payload.
  • MailWebhook posts that payload as JSON to the route endpoint.
  • The request uses POST with Content-Type: application/json.
  • The body is exactly the pipeline output bytes.
  • No additional envelope is added outside the payload.

For the full HTTP request contract, including signatures, idempotency, endpoint headers, and URL restrictions, see Endpoints.

Generic JSON

map.generic_json emits the default MailWebhook payload.

Use it when you want a stable normalized email object with:

  • schema
  • event
  • message
  • body
  • meta
  • optional envelope

The schema identifies the payload as:

{
  "schema": {
    "name": "mailwebhook.generic",
    "version": "1"
  }
}

Generic JSON is deterministic:

  • People arrays are sorted by email.
  • Email addresses are lowercased and trimmed.
  • Headers are lowercased and normalized.
  • Times are UTC whole-second timestamps.
  • Empty optional fields are omitted.
  • Attachment descriptors are sorted and included in body.attachments.

Read next:

Custom JSON

map.custom_json emits the JSON shape you define.

Use it when the receiver expects fields such as:

  • ticket_id
  • customer_email
  • invoice_number
  • alert_source
  • plain_text
  • attachments

Custom JSON maps from a runtime evaluation root that includes parsed message fields, headers, attachments, context, static mapper metadata, and computed variables.

The evaluated output value is sent as the webhook body. It can be an object, array, string, number, boolean, or null. If the top-level output evaluates to null, MailWebhook emits an empty object.

Read next:

Transform steps before mapping

Transform steps can run before the final mapper.

Use them when you need to normalize or remove data before payload mapping:

  • html_to_text: convert HTML into deterministic plain text.
  • remove_fields: remove selected parsed message fields.
  • replace_values: set subject, body, or header values from literals or templates.
  • strip_attachments_if: remove attachments that match MIME, size, or filename conditions.

The final step still must be exactly one map.* mapper.

Read next:

Attachment descriptors

Attachments are not embedded in the webhook body.

Generic JSON includes attachment descriptors in body.attachments. Custom JSON can include message.attachments metadata when you map it into your output.

A Generic JSON attachment descriptor can include:

  • id
  • filename
  • content_type
  • size
  • is_inline
  • content_id
  • sha256

To fetch file content, call the attachment download URL API with X-API-Key. The API returns a short-lived URL with url, expires_at, method, and headers.

Current reference:

Delivery metadata and headers

Keep payload fields separate from delivery headers.

Payload fields are in the JSON body. Delivery metadata is in HTTP headers and event records.

Important delivery headers:

  • X-MailWebhook-Signature
  • X-Idempotency-Key
  • Idempotency-Key, when the customer endpoint headers do not already include either idempotency header variant.

Use these headers in your receiver for verification and idempotent processing. Use Events and Delivery Attempts History to inspect delivery status, response status, and replay behavior.

Current reference:

Quick validation checklist

When inspecting a webhook request, check these first:

  • The request method is POST.
  • Content-Type is application/json.
  • The route pipeline ends with the mapper you expect.
  • Generic JSON payloads have schema.name set to mailwebhook.generic.
  • Generic JSON payloads have schema.version set to 1.
  • Attachment files are represented as metadata, not embedded file bytes.
  • The endpoint returns 2xx for successful delivery.
  • Failed attempts appear in Delivery Attempts History.