Webhooks

Your endpoint receives type and data. Signatures use HMAC SHA-256.

Open Webhooks and add an HTTPS URL. Pigeon POSTs JSON when an email is sent, delivered, bounced, or complained. The signing secret is shown once in the notice after you add the endpoint. Store it then.

Events

A new webhook listens for these four events. type names the event. data.status is sent, delivered, bounced, or complained.

  • email.sent — the message was accepted for delivery.
  • email.delivered — the recipient server accepted it.
  • email.bounced — delivery failed. data.status is bounced.
  • email.complained — the recipient reported it as spam. data.status is complained.

The body is JSON with type, created_at, and data. created_at on the event is the time Pigeon posted it. data is the same email object the API returns: id, from, to, cc, bcc, reply_to, subject, html, text, status, scheduled_at, and created_at. created_at inside data is the time the email was stored. from is Name <address> when the message has a sender name, and the address alone otherwise.

Example

JSON
{
  "type": "email.delivered",
  "created_at": "2026-11-06T12:00:00Z",
  "data": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "from": "Ada <ada@yourdomain.com>",
    "to": ["person@example.com"],
    "cc": [],
    "bcc": [],
    "reply_to": [],
    "subject": "Hello",
    "html": "<p>Hello</p>",
    "text": null,
    "status": "delivered",
    "scheduled_at": null,
    "created_at": "2026-11-06T12:00:00Z"
  }
}

email.sent, email.bounced, and email.complained use the same shape. Change type, and set data.status to sent, bounced, or complained.

Verify the signature

The request header pigeon-signature is the lowercase hex HMAC-SHA256 of the raw request body. The key is the signing secret. Compare the header to your own HMAC of those exact bytes. Reject the request when they differ. Reformatting the JSON changes the signature.

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

export function verifyPigeonWebhook(secret, rawBody, signature) {
  const digest = createHmac("sha256", secret).update(rawBody).digest("hex");
  const left = Buffer.from(digest);
  const right = Buffer.from(signature || "");
  return left.length === right.length && timingSafeEqual(left, right);
}

const ok = verifyPigeonWebhook(
  secret,
  rawBody,
  request.headers["pigeon-signature"]
);

A marketing list signup uses X-Pigeon-Signature, X-Pigeon-Timestamp, and X-Pigeon-Idempotency-Key. The Marketing guide describes that request.

Marketing list signups

Inbound mail

Inbound mail can be posted to /webhooks/inbound/:INBOUND_WEBHOOK_TOKEN with from, to, subject, and text or html. The recipient domain must already be verified. If every recipient is an address created in Incoming, the subject and body are stored encrypted and do not count toward the quota. Any other recipient on a verified domain is stored on Receiving and counts toward the quota. A mix of the two is refused.