Email.com docsOpen the app

Guides

Receiving webhooks

Every customer-visible platform event (message lifecycle, suppression changes, domain verification and the webhook endpoint's own lifecycle) can be delivered to HTTPS endpoints you register. You manage endpoints through the API or the panel; delivery, retries and signing run on managed infrastructure, and this guide covers what your receiver must do and what the platform guarantees. The event types you can subscribe to, with the JSON Schema of each, are listed in the event type catalog (GET /v1/webhooks/event-types).

Register an endpoint

Create an endpoint in the panel (Webhooks, New endpoint) or with POST /v1/webhooks/endpoints: an HTTPS URL, an optional description and the event types you want (exact catalog types such as email.delivered.v1). The response includes the endpoint id. Every endpoint has its own signing secret: read it once with GET /v1/webhooks/endpoints/{endpoint_id}/secret and store it in your secret manager. The platform never shows it in logs, and you can rotate it at any time.

What you receive

Each delivery is a POST with a JSON body and three headers. The body is the catalog event as the producer emitted it:

FieldMeaning
idThe event id (evt_...), unique and time-ordered. Use it to deduplicate.
typeThe event type, for example email.delivered.v1.
occurred_atWhen the event happened (RFC 3339, UTC). Use it, not the arrival time, to order events.
tenant_idYour account id.
stream_idThe stream of a sending event, when there is one.
subjectWhat the event is about: { "kind": "message", "id": "msg_..." } for message events, { "kind": "webhook_endpoint", "id": "wh_..." } for endpoint events.
dataThe event payload exactly as the producing product wrote it. It carries ids and hashes (for example message_id, recipient_hash), never an address, a subject or a body.
testtrue on test events only.

The headers follow the Standard Webhooks specification:

HeaderMeaning
webhook-idThe delivery service's message id. It stays the same across retries of one delivery; deduplicate on the body id, not on this header.
webhook-timestampUnix seconds when this attempt was signed.
webhook-signatureOne or more space-separated signatures, each v1,<base64>. Several appear while a rotated secret is still valid.

Answer with any 2xx status within 15 seconds to acknowledge, and do your real work after acknowledging. Anything else, a timeout or a connection error counts as a failed attempt.

Verify every delivery

Verify the signatures over the raw request body, byte for byte, before you parse it: a body re-serialized by a framework no longer matches. The signed content is <webhook-id>.<webhook-timestamp>.<raw body>, the key is the base64 part of your secret after the whsec_ prefix, the algorithm is HMAC-SHA256, and the result is compared in constant time against each v1 signature. Refuse a timestamp more than five minutes away from your clock: it stops replays of captured requests. Reject anything that fails.

Any Standard Webhooks library does this for you (standardwebhooks on npm and PyPI, and libraries for most languages). Without a library, in Node.js:

`js verify-example import { createHmac, timingSafeEqual } from 'node:crypto';

/** Returns the parsed event when a v1 signature matches; throws otherwise. */ export function verifyWebhook(secret, headers, rawBody, toleranceSeconds = 300) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatures = headers['webhook-signature']; if (!id || !timestamp || !signatures) throw new Error('missing webhook headers'); const sentAt = Number(timestamp); if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > toleranceSeconds) { throw new Error('webhook timestamp outside the tolerance'); } const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64'); const expected = createHmac('sha256', key).update(${id}.${timestamp}.${rawBody}).digest(); for (const candidate of signatures.split(' ')) { const [version, value] = candidate.split(','); if (version !== 'v1' || !value) continue; const given = Buffer.from(value, 'base64'); if (given.length === expected.length && timingSafeEqual(given, expected)) return JSON.parse(rawBody); } throw new Error('no valid webhook signature'); } `

In Python:

`python verify-example import base64, binascii, hashlib, hmac, json, time

def verify_webhook(secret, headers, raw_body, tolerance_seconds=300): """Returns the parsed event when a v1 signature matches; raises otherwise.""" msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not msg_id or not timestamp or not signatures: raise ValueError("missing webhook headers") if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance_seconds: raise ValueError("webhook timestamp outside the tolerance") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = hmac.new(key, signed, hashlib.sha256).digest() for candidate in signatures.split(" "): version, _, value = candidate.partition(",") if version != "v1" or not value: continue try: given = base64.b64decode(value, validate=True) except (binascii.Error, ValueError): continue # a malformed candidate never hides a valid one after it if hmac.compare_digest(given, expected): return json.loads(raw_body) raise ValueError("no valid webhook signature") `

Read the raw body before any JSON middleware runs (in Express, express.raw({ type: 'application/json' }) on the webhook route), and keep the secret in your secret store, never in code.

Retries, duplicates and what is up to you

The embedded portal

The panel embeds a delivery portal (Webhooks, Portal; POST /v1/webhooks/portal answers a short-lived URL) that shows your endpoints, deliveries and attempts. The portal session is read-only: create and change endpoints in the panel or through the API, where approvals and the endpoint history apply. Endpoints that exist only at the delivery service (for example created in an earlier portal session) are not shown in the panel or the endpoint list, are not checked by the URL safety rules or the endpoint limit, and can be removed by an operator's reconciliation apply step.

Events about your endpoints

TypeWhen
webhook.endpoint.created.v1An endpoint was created.
webhook.endpoint.disabled.v1An endpoint or one of its types was paused, or the endpoint was disabled after repeated failures.
webhook.delivery.failed.v1An endpoint started failing (once per failing episode).
webhook.delivery.recovered.v1A failing endpoint delivers again.

Subscribe another endpoint to these types to monitor your integration.