Events Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Events Tracking records and manages specific actions within the Resend ecosystem. The system handles two primary types of events: custom application events used for automation and tracking, and system-level webhook events that notify external services about email, contact, and domain activities.
The Events class provides methods to create, send, and manage custom event definitions. These events allow you to track user behaviors like "user.created" and associate them with specific contacts or email addresses.
Custom Events Management
The Events module manages the lifecycle of custom event definitions. You define events with specific schemas to validate the data payloads sent during tracking.
Architecture and Data Flow
When you send an event, the system maps camelCase identifiers like contactId to snake_case contact_id before transmitting data to the API.
The diagram shows the transformation of event payloads before they reach the Resend API.
Sources: src/events/events.ts:25-30, src/common/utils/parse-automation-to-api-options.spec.ts:182-192
Key Methods
The Events class implements the following operations:
| Method | Endpoint | Description |
|---|---|---|
send | POST /events/send | Records an occurrence of an event for a contact or email. |
create | POST /events | Creates a new event definition with a validation schema. |
get | GET /events/:id | Retrieves details of a specific event definition. |
list | GET /events | Returns a paginated list of event definitions. |
update | PATCH /events/:id | Modifies an existing event definition schema or name. |
remove | DELETE /events/:id | Deletes an event definition. |
Sources: src/events/events.ts:1-75, src/events/events.spec.ts:14-250
Webhook Events
Webhook events represent system-generated notifications. The system triggers these events when specific actions occur, such as an email being delivered or a contact being updated.
Event Categories
The system categorizes webhook events by the resource they affect.
The diagram illustrates the hierarchical structure of system-generated webhook event types.
Sources: src/webhooks/interfaces/webhook-event.interface.ts:11-50
Webhook Event Interface
Every webhook event contains a type, a creation timestamp, and a data payload specific to that event type.
| Field | Type | Description |
|---|---|---|
type | WebhookEvent | The specific action name (e.g., email.opened). |
created_at | string | ISO 8601 timestamp of when the event occurred. |
data | object | Detailed payload (e.g., email_id, from, to, subject). |
Sources: src/webhooks/interfaces/webhook-event.interface.ts:204-215
Webhook Verification
The Webhooks class includes a verify method to ensure that incoming webhook payloads are genuine and originate from Resend.
Verification Flow
To verify a webhook, you must provide the raw payload string, the specific headers received (id, timestamp, signature), and your webhook signing secret.
The sequence diagram shows how the SDK validates webhook authenticity using the standardwebhooks library.
Sources: src/webhooks/webhooks.ts:110-120, src/webhooks/webhooks.spec.ts:515-535
Webhook Event History and Replays
Resend maintains a log of webhook events and their delivery attempts. You can access this history to debug integration issues or replay failed deliveries.
Replay Logic
If a webhook delivery fails, you can trigger a replay. This instructs the Resend API to attempt sending the event notification to your endpoint again.
| Feature | Description |
|---|---|
| List Events | Retrieves all webhook events associated with a specific webhook ID. |
| Get Event | Retrieves a single webhook event by ID to inspect its payload. |
| Replay Event | Retriggers the webhook notification for a specific event. |
| List Attempts | Lists individual HTTP delivery attempts for a webhook event, including status codes. |
Sources: src/webhooks/events/events.ts:20-65, src/webhooks/webhooks.spec.ts:145-280
Conclusion
Events Tracking provides the infrastructure for both inbound and outbound activity monitoring. Custom events allow applications to feed data into Resend automations, while webhook events provide a real-time feedback loop for email delivery and resource changes. The system ensures security through cryptographic signature verification and provides reliability through event logging and manual replay capabilities.