Inbound webhooks, signed

create_webhook {
  url: "https://your-service.dev/hooks/sending",
  events: ["email.received", "email.bounced"]
}
→ { id, secret }   # the secret is shown once

The secret is returned at creation and never again, like an API key. Deliveries are recorded, so when your endpoint was down for an hour you can see what we tried to send rather than guessing.

Every delivery carries Sending-Signature: t=,v1=. The signed string is the timestamp, a dot, and the raw body, exactly as received: re-serializing the JSON before hashing is the mistake that makes a correct implementation fail, because key order and spacing change the bytes.

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

// header: Sending-Signature: t=<unix>,v1=<hmac>
function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Compare with a timing-safe function, and reject a timestamp older than your tolerance. An endpoint that skips both is a public inbox for anyone who learns the URL.

Treat it as a signal, not as the message. The payload tells you which inbox and which thread moved; read the thread when you are ready to act on it. That way a burst of mail does not turn into a burst of half-finished work, and a redelivery does not make your agent answer twice.

Deliveries are at-least-once by design. Make the handler idempotent on the message id, because the alternative is a duplicate reply to a customer who only wrote once.