Webhooks Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Webhooks Configuration module provides tools to manage and verify webhooks within the Resend Node.js SDK. This system allows you to receive real-time notifications about events such as email delivery, bounces, and contact updates by configuring HTTP endpoints that Resend calls when these events occur.
Core Management API
The Webhooks class manages the lifecycle of webhook endpoints. It interacts with the Resend API to perform CRUD operations on webhook configurations.
Lifecycle Operations
You can perform the following actions to configure webhooks:
- Create: Register a new endpoint URL and specify which event types it should receive.
- List/Get: Retrieve details of existing configurations, including their unique IDs and current statuses.
- Update: Modify the endpoint URL, the list of subscribed events, or the enabled/disabled status.
- Remove: Delete a webhook configuration permanently.
- Rotate Secret: Generate a new signing secret for an existing webhook to maintain security.
Sources: src/webhooks/webhooks.ts:40-109, src/webhooks/interfaces/list-webhooks.interface.ts:7-13
Webhook Object Structure
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the webhook configuration. |
endpoint | string | The URL where Resend sends POST requests. |
created_at | string | Timestamp of when the webhook was created. |
status | 'enabled' | 'disabled' | Current operational state of the webhook. |
events | WebhookEvent[] | List of events the endpoint is subscribed to. |
Sources: src/webhooks/interfaces/list-webhooks.interface.ts:7-13
Payload Verification
Resend signs every webhook payload to ensure the request originated from its servers and was not tampered with. The SDK uses the standardwebhooks library to perform this validation.
Verification Logic
To verify a webhook, you must provide the raw request payload, specific headers (ID, timestamp, and signature), and your webhook-specific signing secret.
The diagram above shows the security flow for handling an incoming webhook request.
Sources: src/webhooks/webhooks.ts:111-120, src/webhooks/webhooks.spec.ts:581-618
Headers Required for Verification
| Header Key | SDK Identifier | Description |
|---|---|---|
webhook-id | headers.id | Unique ID of the webhook event. |
webhook-timestamp | headers.timestamp | Epoch timestamp of the request. |
webhook-signature | headers.signature | Cryptographic signature generated by Resend. |
Sources: src/webhooks/webhooks.ts:111-120, src/webhooks/webhooks.spec.ts:596-600
Supported Webhook Events
The configuration allows subscription to various event categories across the Resend platform. Subscribing to specific events minimizes unnecessary traffic to your endpoint.
Event Categories
- Email Tracking:
email.sent,email.delivered,email.bounced,email.opened,email.clicked. - Contact Management:
contact.created,contact.updated,contact.deleted. - Domain Status:
domain.created,domain.updated,domain.deleted. - Inbox & Threads:
inbox.thread.created,inbox.email.received,inbox.draft.sent.
Sources: src/webhooks/interfaces/webhook-event.interface.ts:10-46
Architecture and Data Flow
The Webhooks class is initialized as a member of the main Resend client. It uses the internal fetchRequest mechanism to communicate with the /webhooks API endpoints.
The sequence diagram illustrates the configuration phase followed by the runtime event delivery and verification process.
Sources: src/resend.ts:59, src/webhooks/webhooks.ts:40-120, src/webhooks/webhooks.spec.ts:40-80
Conclusion
The Webhooks Configuration system enables secure, programmatic management of event notifications. By combining CRUD operations with standard cryptographic verification, it ensures that your application reacts only to authentic and authorized events from the Resend platform.