# Handle events

Part of **Resend**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to receive real-time notifications from Resend about email lifecycle events—such as when an email is opened, a link is clicked, a message bounces, or a domain is created—and reliably process or store that data. This requires setting up secure, verified webhook endpoints that Resend can deliver `email events` to.

**Typical User Questions**:
- How to get notified when an email is opened?
- Can I track link clicks in emails?
- How to set up webhooks for bounces?
- How to store webhook data from Resend?
- How to verify webhook authenticity?

## Decision Tree

Pick the best path for your situation:

- **If** you need to create or delete webhook endpoints using code (e.g., in CI/CD or infrastructure-as-code) → Use **Webhook Configuration via API** (go to *resend/resend-webhooks*)
- **If** you want to manually configure webhooks via UI, replay messages, or deploy the **Webhook Ingester** for storage → Use **Webhook Setup and Data Handling Guide** (go to *resend/resend-webhooks*)
- **If** you are building handlers for specific events like `email.bounced`, `domain.created`, or click tracking that require immediate `200 OK` responses and custom signature verification using `x-resend-signature` → Use **Event-Specific Webhook Handlers** (go to *resend/resend-sending*)
- **Otherwise (default)** → Start with **Webhook Setup and Data Handling Guide** — it provides the most beginner-friendly onboarding, includes the **Replay button** for debugging, and supports deployment of a reference storage solution with minimal coding.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Webhook Configuration via API | When programmatically managing webhook endpoints and event subscriptions. | medium | Yes | Yes | Uses `POST /webhooks` API and requires `raw request body` for signature verification | `resend/api/resend-webhooks` |
| Webhook Setup and Data Handling Guide | When learning how to receive, store, and replay webhook events reliably. | medium | Yes | No | Includes **Add Webhook button**, **Events to observe checkbox**, and **Webhook Ingester** deployment guide | `resend/guide/resend-webhooks` |
| Event-Specific Webhook Handlers | When implementing handlers for specific events like bounces, clicks, or domain changes. | high | Yes | Yes | Requires `HMAC-SHA256` verification of `x-resend-signature` and immediate `200 OK` response | `resend/api/resend-sending` |

## Path Details

### Path 1: Webhook Configuration via API

**Best For**: When programmatically managing webhook endpoints and event subscriptions.

**Brief Description**: The Resend webhooks API is a synchronous REST service that lets you create, list, update, and delete webhook endpoints via `POST /webhooks` and related endpoints. It integrates with the `Webhook class from svix library` for verification and requires handling the `raw request body` to validate signatures correctly.

**Key technical facts**:
- Billing: Webhook management and verification are included in Resend’s core email API service at no additional cost.

**When to Use**:
- Need to programmatically manage webhook endpoints in CI/CD pipelines
- Building infrastructure-as-code deployments for webhook configuration
- Automating webhook creation/deletion based on environment lifecycle

**When NOT to Use**:
- User prefers UI-based configuration without writing code
- Need to replay individual webhook messages manually
- Want to deploy reference storage solution like Webhook Ingester without coding

**Known Limitations**:
- Each webhook has its own unique signing secret — cannot reuse secrets across webhooks
- Must use raw request body (not parsed/re-stringified) for signature verification to avoid mismatch
- Webhook URL must be a valid HTTPS URL
- Requires separate RESEND_WEBHOOK_SECRET distinct from API key

### Path 2: Webhook Setup and Data Handling Guide

**Best For**: When learning how to receive, store, and replay webhook events reliably.

**Brief Description**: This guide uses the Resend Console to configure webhooks through the **Add Webhook button**, where you enter a **Webhook URL text_input**, select events using the **Events to observe checkbox**, and obtain a **Signing Secret**. It also covers deploying the open-source **Webhook Ingester** to store events in PostgreSQL/MySQL/MongoDB and using the **Replay button** to re-send past events. For local testing, it recommends **ngrok** to expose a local endpoint.

**Key technical facts**:
- Billing: Webhooks are free to use and billed per event delivery. No additional charges apply.
- Prerequisites include a publicly accessible **HTTPS URL**, **ngrok** for development, and **Developer role** access in the Resend dashboard.

**When to Use**:
- Learning how to manually configure and test webhooks through UI
- Need to replay specific failed/successful webhook messages for debugging
- Want to deploy reference storage solution (Webhook Ingester) with minimal coding

**When NOT to Use**:
- Need programmatic webhook management for automated environments
- Building headless integrations without UI interaction
- Require fine-grained control over webhook lifecycle via API

**Known Limitations**:
- Webhook Ingester deployment requires external setup outside Resend console
- Message retention period for replay is not specified in documentation
- Requires Developer or Owner role access to manage webhooks in console
- If no events are selected in 'Events to observe', no events will be sent

### Path 3: Event-Specific Webhook Handlers

**Best For**: When implementing handlers for specific events like bounces, clicks, or domain changes.

**Brief Description**: This approach focuses on processing specific `webhook event` types such as `email.bounced`, `email.delivered`, and `domain.created`. Your endpoint must verify payloads using the `x-resend-signature` header with `HMAC-SHA256`, handle the `raw request body`, and return a `200 OK` response immediately. It supports tracking engagement and handling system events like domain lifecycle changes or `suppressed` addresses.

**Key technical facts**:
- Billing: Per-request billing — you pay for each email sent and each webhook event delivered. Monthly 1000 free requests for email sending; 10,000 free webhook events per month.
- Rate limit: 100 requests per minute per endpoint
- Requires immediate 2xx response to acknowledge receipt

**When to Use**:
- Implementing specialized handlers for critical email events like bounces or spam complaints
- Need to integrate domain lifecycle events (creation/deletion) into application logic
- Building custom analytics for email engagement (opens/clicks) with verified payloads

**When NOT to Use**:
- Need general-purpose webhook management rather than event-specific handling
- Prefer Svix-standard signature verification over Resend's custom `x-resend-signature`
- Want to use UI-based replay features instead of programmatic event processing

**Known Limitations**:
- Webhook endpoints have rate limit of 100 requests per minute per endpoint
- Must verify signatures using `x-resend-signature` header with `HMAC-SHA256`
- Requires immediate `200 OK` response to acknowledge receipt (no long processing)
- Different signature verification method than Svix standard used in other paths (uses `x-resend-signature` instead of `svix-*` headers)

## FAQ

Q: Which path should I start with?
A: Start with **Webhook Setup and Data Handling Guide** if you're new to Resend webhooks—it offers UI configuration, the **Replay button** for debugging, and the **Webhook Ingester** for storage with minimal code.

Q: What if I need to replay a failed webhook but chose Webhook Configuration via API?
A: You’ll hit a dead end—programmatic management via `POST /webhooks` does not include message replay capabilities. Only the Console-based **Replay button** (in the Guide path) supports this.

Q: What if I use a parsed JSON body instead of the raw request body for signature verification?
A: Signature verification will fail across all paths because Resend requires the exact byte sequence. This is explicitly noted in limitations for both the API and Event-Specific paths.

Q: What if I’m handling `email.bounced` events but use the Svix library expecting `svix-*` headers?
A: You’ll fail to verify signatures because Event-Specific Handlers use Resend’s custom `x-resend-signature` header with `HMAC-SHA256`, not the Svix standard. This mismatch causes authentication errors.

Q: Can I use HTTP instead of HTTPS for my webhook URL?
A: No—all paths require a valid **HTTPS URL**. Resend will reject any webhook endpoint that uses HTTP, as stated in the limitations of the API path and implied by security best practices in the others.

Q: What happens if I don’t select any events in the **Events to observe checkbox**?
A: No `email events` will be delivered to your endpoint—even if it’s correctly configured. This is a silent failure mode documented in the Guide path’s limitations.

Q: Do I need a **Developer role** to use the API-based paths?
A: No—role requirements only apply to Console actions like clicking **Add Webhook button**. API paths only require a valid `RESEND_API_KEY`, regardless of dashboard permissions.

## Related queries

receive email events, process email events, handle email webhooks, email event notifications, track email opens, track link clicks, set up email webhooks, verify webhook authenticity, store webhook data, replay webhook events, how to get email open notifications, can I track email clicks, setup boun

---
Part of [Resend](https://www.company-skill.com/p/resend.md) · https://www.company-skill.com/llms.txt