Webhooks & Events API

Relevant source files

The following files were used as context for generating this wiki page:

• src/webhooks.rs
• src/events.rs
• examples/axum-verify-event-middleware.rs
• src/lib.rs
• src/automations.rs
• CHANGELOG.md

The Webhooks & Events API provides tools to manage real-time notifications and programmatic event triggers within the Resend ecosystem. The WebhookSvc manages endpoint configurations that receive notifications about email and system activity, while the EventsSvc allows users to create and send custom events that trigger automations.

This module provides structures for parsing incoming payloads, verifying request signatures, and managing the lifecycle of webhook endpoints. It integrates with other systems like Automations by serving as the data source for sequence triggers.
Sources: src/webhooks.rs:17-20, src/events.rs:27-30, src/lib.rs:88-91

Webhook Management

The WebhookSvc struct provides methods to manage webhook endpoints. You can create, retrieve, update, and delete webhooks to monitor specific events such as sent, delivered, or bounced emails.

Webhook Lifecycle Flow

The following diagram illustrates the lifecycle of a webhook from creation to secret rotation.

Core Webhook Methods

Method	Description	Path
create	Creates a new webhook for specified events.	POST /webhooks
get	Retrieves a single webhook by ID.	GET /webhooks/{id}
update	Modifies endpoint URL, events, or status.	PATCH /webhooks/{id}
delete	Removes an existing webhook.	DELETE /webhooks/{id}
rotate_signing_secret	Generates a new secret; old one works for 24 hours.	POST /webhooks/{id}/signing-secret/rotate
replay_event	Queues a delivery attempt for a specific event.	POST /webhooks/{id}/events/{event_id}/replay

Sources: src/webhooks.rs:24-110, CHANGELOG.md:46-52

Event System Architecture

Resend uses a strongly-typed event system to represent different categories of system activity. The SDK provides try_parse_event to deserialize raw JSON payloads into a comprehensive Event enum.

Event Type Hierarchy

The system categorizes events into specific types, each containing a specialized data body.

Supported Event Categories

Category	Event Types (Examples)	Data Body
Email	email.sent, email.bounced, email.delivered	EmailBody
Contact	contact.created, contact.updated, contact.deleted	ContactBody
Domain	domain.created, domain.deleted	Domain
Inbox	inbox.thread.created, inbox.email.received	InboxEvent
Topic	topic.created, topic.updated	TopicBody

Sources: src/events.rs:231-318

Custom Automation Events

The EventsSvc allows you to define custom schemas and send events that trigger automations. This is distinct from system-generated webhooks.

• Create Event: Defines a named event with a JSON schema.
• Send Event: Triggers matching automations by sending a payload for a specific contact or email.

Webhook Security and Verification

Verification ensures that incoming requests originate from Resend. The SDK example demonstrates using the svix crate to verify the Idempotency-Key and signing secret against the request headers and raw body bytes.

Verification Steps

1. Extract the raw request body as bytes.
2. Retrieve the whsec_ signing secret from the Resend dashboard.
3. Initialize a Webhook verifier.
4. Execute the verify method with body bytes and header map.
5. Parse the verified body using try_parse_event.

Sources: examples/axum-verify-event-middleware.rs:52-64, src/events.rs:141-152

Data Models

Webhook Configuration

The CreateWebhookOptions struct requires a target endpoint and a list of event types.

pub struct CreateWebhookOptions {
    endpoint: String,
    events: Vec<EventType>,
}

Sources: src/webhooks.rs:202-205

Event Delivery Attempts

Webhooks track delivery history through attempts. Each attempt includes the HTTP status code and the server response.
Sources: src/webhooks.rs:189-194

Summary

The Webhooks & Events API facilitates real-time observability and automation control. By managing webhook endpoints and parsing typed events, developers integrate Resend activity directly into their application workflows while maintaining security through cryptographic verification.