Webhooks

Pro Providers notify you of delivery events — opens, clicks, bounces, complaints, unsubscribes — via webhooks, each with its own payload shape and (sometimes) its own signature scheme. email.webhooks.handle() verifies the signature inside the adapter and hands you one normalized EmailEvent[], so you write a single handler no matter which providers are live. Webhook normalization is a Pro feature — call await email.init() first.

const events = await email.webhooks.handle({
  body: req.rawBody,     // the RAW bytes — see below
  headers: req.headers,
});

for (const e of events) {
  switch (e.type) {
    case "delivered":    break;
    case "bounced":      /* e.bounce?.type is "hard" | "soft" */ break;
    case "complained":   break;
    case "unsubscribed": break;
    case "opened":
    case "clicked":      break;
  }
}

The three signature tiers

Providers fall into three groups. capabilities.webhooks and capabilities.webhookSignature tell you which tier a provider is in.

• Signed & verified — Radon cryptographically verifies the signature before normalizing (Svix, ECDSA, SNS-RSA, HMAC-SHA256). A bad signature throws WebhookSignatureError. Both capability flags are true.
• Normalized, unsigned — the provider ships no body signature. Radon still normalizes the payload, but there's nothing to verify, so you must secure the endpoint (a secret URL path, basic auth, an IP allowlist). webhooks: true, webhookSignature: false.
• No delivery webhook — the provider has no signed delivery webhook Radon can normalize. handle() for these throws UnsupportedOperationError. Both flags are false.

Always pass the raw body

Signatures are computed over the exact bytes the provider sent. If your framework has already parsed the body into an object and re-serialized it, verification will fail. Give Radon the raw string or Buffer.

import { email } from "@/lib/email";

export async function POST(req: Request) {
  const body = await req.text(); // raw string — do NOT req.json()
  const headers = Object.fromEntries(req.headers);

  try {
    const events = await email.webhooks.handle(
      { body, headers },
      { provider: "resend" },
    );
    // handle events…
    return new Response(null, { status: 200 });
  } catch {
    return new Response(null, { status: 400 }); // signature failed → reject
  }
}

Configure the signing secret

Each signed provider needs its verification secret, read from the provider's webhookSecret option or a RADON_<PROVIDER>_* env var:

RADON_RESEND_WEBHOOK_SECRET=whsec_...              # Svix signing secret
RADON_SENDGRID_WEBHOOK_VERIFICATION_KEY=...        # base64 ECDSA public key
RADON_MAILGUN_WEBHOOK_SECRET=...                   # HTTP webhook signing key
RADON_MAILERSEND_WEBHOOK_SECRET=...                # HMAC secret

Amazon SES is the exception: it needs no configured secret. Its events arrive via SNS, and Radon verifies each message against the RSA certificate at the SNS SigningCertURL (restricted to *.amazonaws.com). You can override any provider's secret per call with options.secret.

Disambiguating the provider

With one provider configured, Radon infers it — options.provider is optional. With several, you must say which adapter should verify the request, or handle() throws InvalidConfigError.

// One provider configured → inferred:
await email.webhooks.handle({ body, headers });

// Several configured → name the one this endpoint belongs to:
await email.webhooks.handle({ body, headers }, { provider: "sendgrid" });

The usual pattern is one route per provider (/webhooks/resend, /webhooks/sendgrid), each passing its own provider.

Normalized event types

Every provider's events map into one vocabulary — branch on event.type:

The EmailEvent shape

React with hooks instead

By default handle() also dispatches each event to any registered lifecycle hooks — a clean way to keep bounce-suppression logic out of your route. Register handlers with email.on(...):

email.on("onBounced", (e) => suppress(e.recipient));
email.on("onComplained", (e) => suppress(e.recipient));
email.on("onUnsubscribed", (e) => unsubscribe(e.recipient));
email.on("onEmailEvent", (e) => log(e)); // catch-all, fires for every event

// The route just verifies and returns — hooks do the work.
await email.webhooks.handle({ body, headers }, { provider: "resend" });

Pass { dispatch: false } to handle() if you want to parse only and skip the hooks. Hook failures are isolated — a throwing handler is reported via onEventError and never breaks the request.

handle() signature

Next steps