Resend webhooks: a practical guide to events, verification, and retries

Resend webhooks are how your backend finds out what happened to an email after you handed it off: delivered, bounced, complained, opened, clicked. We run Resend webhooks in production at GetFluxly, where they feed email analytics and suppression, so this guide is written from the endpoint side rather than the dashboard side. It covers the full event list, what a payload actually looks like, how to verify the Svix signature without the two mistakes that catch almost everyone, why your handler has to be idempotent, how retries behave, and the things about running this in production that no tutorial mentions.

The Resend webhook event types.

Resend organizes webhooks into four families. Email events describe the life of a single message and are what most integrations subscribe to. Contact events (contact.created, contact.updated, contact.deleted) and domain events (domain.created, domain.updated, domain.deleted) cover account level changes and are useful mostly if you manage audiences or domains programmatically. Suppression events (suppression.added, suppression.removed) fire when an address goes onto or comes off your suppression list, which is worth subscribing to if you mirror suppressions in your own database. You choose which events a given webhook receives when you create it, so start narrow and add more as you need them. The email events are the ones worth knowing cold.

A note on opens and clicks: email.opened and email.clicked only fire if you enable open tracking and click tracking on the sending domain, and both come with the caveats that make engagement data soft. If your goal is to measure what those signals actually predict rather than just count them, the companion piece on Resend email analytics covers why open rates overcount and how to tie the events to real behavior.

What a webhook payload looks like.

Every event is a JSON object with the same top level shape: a type field naming the event, a created_at timestamp for when the event happened, and a data object with the details. Here is a real email.sent payload, which is the baseline every other email event builds on.

{
  "type": "email.sent",
  "created_at": "2023-02-22T23:41:12.126Z",
  "data": {
    "created_at": "2023-02-22T23:41:11.894719+00:00",
    "email_id": "56761188-7520-42d8-8898-ff6fc54ce618",
    "from": "Acme <onboarding@resend.dev>",
    "to": ["delivered@resend.dev"],
    "subject": "Sending this example"
  }
}

Note that data.to is an array, not a string, which trips up handlers that assume a single recipient. The data object carries the email_id you use to correlate the event back to the message you sent, along with from, to, and subject. Specific events extend the data object: email.clicked adds a click object with the link that was followed, a timestamp, the IP address, and the user agent; email.bounced adds a bounce object describing the failure, including whether it was a hard or soft bounce. Read defensively. Providers add fields over time, and a subtype your code has never seen should degrade to a safe default rather than throw.

Verifying the signature with Svix.

Your webhook endpoint is public, so anyone who finds the URL can POST to it. Verification is the only thing standing between a real Resend event and a forged one, and skipping it means an attacker can invent bounce or complaint events and corrupt your send log. Resend signs every webhook through Svix, which means three headers travel with each request: svix-id (a unique message id), svix-timestamp (when it was signed), and svix-signature (the signature itself). The Svix library turns verification into one call.

import express from "express";
import { Webhook } from "svix";

const app = express();
const wh = new Webhook(process.env.RESEND_WEBHOOK_SECRET);

app.post(
  "/webhooks/resend",
  express.raw({ type: "application/json" }), // keep the raw bytes
  async (req, res) => {
    let event;
    try {
      // req.body is a Buffer here. Verify the buffer, never
      // JSON.stringify(req.body): re-serializing changes the bytes
      // and the signature will not match.
      event = wh.verify(req.body, {
        "svix-id": req.get("svix-id"),
        "svix-timestamp": req.get("svix-timestamp"),
        "svix-signature": req.get("svix-signature"),
      });
    } catch (err) {
      return res.status(401).send("invalid signature");
    }

    try {
      // enqueue is your durable queue adapter. It must save the payload
      // before resolving and dedupe on svix-id, including concurrent retries.
      await enqueue(req.get("svix-id"), event);
    } catch {
      // No durable copy means no success response. Let Resend retry.
      return res.status(503).send("queue unavailable");
    }

    // A worker can now process the saved event after this request ends.
    return res.status(200).send("ok");
  },
);

Supply enqueue from your own queue adapter. Its promise must resolve only after the payload is committed to durable storage, or after it confirms that the same svix-id is already saved. Put the unique event id and payload in one atomic write. A memory queue, a detached promise, or a saved id without its payload does not meet this contract. Register this route before any global express.json() middleware. For the Next.js version and signature details, see the Resend signature verification guide.

Two mistakes cause almost every verification failure, and both pass in a quick local test. The first is verifying the wrong bytes. The signature is computed over the exact raw body Resend sent, so the instant a body parser turns the request into a JavaScript object, the original byte sequence is gone and re-serializing it with JSON.stringify will not reproduce it. That is why the example uses express.raw and hands the buffer straight to verify. In Next.js route handlers, call req.text() and verify the string before you parse it.

The second mistake is ignoring the timestamp. Without a freshness check, anyone who captures one valid payload can replay it forever. The Svix libraries reject timestamps outside a five minute window for you. If you verify by hand, as we do in our Python backend, you have to add that check yourself: parse svix-timestamp, compare it to now, and reject anything outside roughly five minutes in either direction before you even bother computing the HMAC. When we implemented the scheme directly, the details that mattered were stripping the whsec_ prefix and base64 decoding the secret before using it as the HMAC key, signing the string that joins the id, the timestamp, and the raw body with periods, and comparing the v1 token in constant time.

Idempotency: webhooks retry, so dedupe by event id.

A webhook is an at-least-once delivery, not an exactly-once one. Resend will re-send an event if it does not get a timely success, and it may occasionally deliver the same event twice even when your endpoint succeeded, because the acknowledgement got lost on the way back. If your handler increments a counter, sends an internal alert, or writes a row on every delivery, a single retried event quietly doubles it. The handler has to be idempotent.

The clean fix is to dedupe on the svix-id header, which is stable across every retry of a given event. Record the id the first time you process an event, and when an event arrives with an id you have already stored, return a 200 and stop. Make the event id unique in durable storage so simultaneous deliveries cannot both insert it. Keep deduplication records for your manual replay and recovery period, which may be longer than the automatic retry schedule. Beyond deduping, design each side effect so that running it twice lands in the same place: prefer upserts over inserts, and set a state rather than toggling it.

Save the event before returning 200.

Resend judges your endpoint by the status code and how quickly it comes back. Anything that is not a 2xx counts as a failure and triggers a retry, and a slow handler risks a timeout that also reads as a failure. Verify the signature, save the event to a durable queue, and then return 200. A worker handles the slower business logic after that. Returning success before the save creates a data loss window: the process could exit or the queue could reject the write after Resend has recorded a successful delivery. The example returns 503 if saving fails so a later delivery can try again. Keep the queue write short and configure a timeout for it; do not wait for email analytics or other slow work here.

Resend's retry and replay guide lists the delivery schedule and explains failure notifications. Inspect the next attempt in the dashboard instead of calculating a deadline from a generic Svix example. Repeated endpoint failures can lead to automatic disabling. Fix the cause before enabling it again.

Debug failed deliveries and replay them safely.

Start with the delivery attempt, not just the email status. A failed webhook does not mean the email failed. Check the endpoint response, then verify the signing secret, raw body handling, and queue write for that request. After fixing the handler, replay one event and confirm that it reaches durable storage once before replaying a larger batch.

Resend's September 16 webhook API update adds ways to list events, retrieve a payload, inspect delivery attempts, and request a replay from code. Results are limited by your plan's retention period. A manual replay adds a delivery without cancelling an automatic retry already scheduled for that event, so the same id can arrive again. Keep the queue insert and worker effects idempotent.

Before deploying a handler, test four cases: an invalid signature must save nothing; a queue failure must return 503; a successful save must happen before 200; and two deliveries with the same id must produce one saved event. These checks cover the failure paths a successful test email does not exercise.

Testing Resend webhooks locally.

The obstacle to local development is that Resend needs a public URL and your machine does not have one. A tunnel bridges the gap: run ngrok or cloudflared to expose your local endpoint, register a webhook pointing at the tunnel URL, and send yourself a real email so live events flow to your laptop. This is better than crafting fake payloads by hand, because the events are real and, crucially, they are really signed, so you are exercising your verification path rather than mocking around it.

Lean on the dashboard while you iterate. Resend records every delivery attempt along with the status your endpoint returned, so a 401 tells you verification is failing and a timeout tells you the handler is too slow. The replay button lets you re-fire a captured event against your endpoint as many times as you need, which is the fastest loop for debugging a handler. Keep the signing secret in an environment variable even locally, because testing verification against fake signatures tests nothing.

What we learned running this in production.

The first lesson is that webhook delivered state is eventually consistent, not immediate. An email.delivered event can arrive seconds after the send or, when a receiving server is slow, much later, and a delivery delayed event can precede a delivery that still succeeds. Build your data model so a message can sit in an in between state for a while without anything breaking. If a piece of your product blocks on a delivery confirmation that has not landed yet, you will get support tickets that are really just timing.

The second lesson, which is the one that bites hardest, is to never trust event ordering. Webhooks are not guaranteed to arrive in the order the underlying events occurred, and with retries in the mix a delivered event can genuinely show up after the open event for the same message. Do not write logic that assumes sent comes before delivered comes before opened. Key everything on the message id, treat each event as an independent fact that updates state, and use the timestamp inside the payload rather than the order of arrival when you need to reason about sequence. We also return a 2xx for event types we do not act on, so Resend sees a success and does not retry an event we simply chose to ignore, and we reserve the loud 401 strictly for a signature that fails to verify.

If none of this sounds like work you want to own, that is a reasonable conclusion, and it is why we built the consumer once so our customers do not have to. When you connect Resend to GetFluxly, we run the verified endpoint, the deduplication, the retries, and the suppression for you, and the events land on the customer profile automatically.

Resend webhooks, answered.

What are all the Resend webhook event types?

Resend groups its webhook events into four families. The email events cover the full life of a message: email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.opened, email.clicked, email.failed, email.scheduled, email.suppressed, and email.received for inbound mail. There are also contact events (contact.created, contact.updated, contact.deleted), domain events (domain.created, domain.updated, domain.deleted), and suppression events (suppression.added, suppression.removed) for account level changes. You subscribe to only the events you care about when you create the webhook, so most integrations start with the delivery, bounce, and complaint events and add opens and clicks later.

How do I verify a Resend webhook signature?

Resend delivers webhooks through Svix, so verification follows the Svix scheme. Each request carries three headers: svix-id, svix-timestamp, and svix-signature. The signature is an HMAC-SHA256 computed over the string formed by joining the id, the timestamp, and the raw request body with periods, keyed on your signing secret with its whsec_ prefix stripped and the remainder base64 decoded. The svix-signature header holds one or more space separated tokens like v1,<base64>, and you accept the request if any token matches your computed value using a constant time comparison. The Svix libraries do all of this for you; if you roll your own, those are the exact steps.

What is the most common mistake verifying Resend webhooks?

Verifying against the parsed and re-serialized body instead of the raw bytes. Frameworks love to parse JSON for you, and the moment you call req.json() or let a body parser run, the exact byte sequence Resend signed is gone: key order, whitespace, and number formatting can all shift, and the HMAC no longer matches. You must capture the raw body before anything parses it and verify that. The second most common mistake is skipping the timestamp check, which leaves you open to replay of a captured payload. The Svix libraries enforce a five minute tolerance automatically; a hand rolled verifier has to add it.

Do I need to make Resend webhook handlers idempotent?

Yes. Webhooks retry, and a retry is a re-delivery of an event you may have already processed, so a naive handler will double count. The fix is to dedupe on the event id. The svix-id header is stable across every retry of the same message, which makes it a clean idempotency key: record it when you first process an event, and on any later delivery with an id you have already seen, acknowledge with a 200 and do nothing else. Design every side effect in the handler so that processing the same event twice produces the same result as processing it once.

What is the Resend webhook retry schedule?

Resend's detailed retry guide lists the initial delivery, then retries after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and another 10 hours. Each delay starts after the previous failure. Check the event details for its next attempt. You can also replay failed or successful events, so deduplication must cover manual replays as well as automatic retries.

How do I test Resend webhooks locally?

Your handler needs a public URL, which your laptop does not have, so the usual approach is a tunnel: run a tool like ngrok or cloudflared to expose your local endpoint, then point a Resend webhook at the tunnel URL and send yourself a test email to generate real events. The Resend dashboard shows every delivery attempt with the response your endpoint returned, and lets you replay events, which is the fastest way to iterate on a handler. Keep your signing secret in an environment variable even in development, since the whole point of the exercise is to test verification against real signatures.

Webhooks are simple in shape and unforgiving in the details. Verify the raw body, check the timestamp, dedupe by event id, save before answering 200, and treat every event as an out of order, at-least-once fact about a message you can look up by id. Get those five things right and Resend webhooks become a quiet, reliable feed. For the wider context of making transactional mail itself worth sending, see the guide to transactional email best practices.