Webhooks

Every email MailBridge processes fires a real-time HTTP POST to your endpoint. Build pipelines, sync data, or trigger anything downstream.

Overview

Configure a webhook endpoint in your MailBridge dashboard under Settings → Webhooks. MailBridge will POST a JSON payload to your URL each time a matching event occurs.

Your endpoint must respond with a 2xx status within 10 seconds. Non-2xx responses or timeouts trigger the retry schedule below.

Event types

Payload structure

All events share the same envelope. The data object shape varies by event type.

{
  "event":     "email.triaged",
  "timestamp":  "2025-03-01T09:14:22Z",
  "data": {
    "id":         "req_01JNQX7M4K...",
    "category":   "bug_report",
    "priority":   "high",
    "subject":    "Dashboard not loading",
    "from":       "user@acmecorp.com",
    "summary":    "500 error after login on dashboard",
    "routed_to":  "#bugs"
  }
}

Signature verification

Every request includes a X-MailBridge-Signature header — an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Always verify this before processing.

import crypto from "node:crypto";

function verifySignature(body, secret, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Retry schedule

If your endpoint returns a non-2xx response or times out, MailBridge retries with exponential backoff.