Events Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Events Tracking allows you to define, manage, and trigger custom events associated with your contacts. This system enables monitoring of user behavior, such as sign-ups or plan upgrades, and facilitates integration with automated workflows and real-time notifications.
The system consists of two primary layers:
- Event Definitions: Managing the metadata and schemas for custom events.
- Event Delivery: Processing and transmitting event occurrences via the API or Webhooks.
Sources: resend/events/_events.py, examples/events.py
Event Management
The Events class provides methods to create, retrieve, update, and delete event definitions. Each event requires a unique name and can optionally include a schema to validate the payload data.
Event Definition Lifecycle
When you create an event, you define a name and an optional schema. The schema is a flat map of keys to data types. Supported types include string, number, boolean, and date. You can update an existing event's schema or delete the event definition entirely using its ID or name.
Sources: resend/events/_events.py:20-64, examples/events.py:22-40
The diagram above shows the lifecycle of an event definition from creation to deletion.
Event Methods and Parameters
| Method | Parameters | Description |
|---|---|---|
create() | name, schema | Creates a new event definition. Name cannot start with resend:. |
get() | identifier | Retrieves a definition by UUID or name. |
update() | identifier, schema | Updates the schema for a definition. Set schema to None to clear it. |
remove() | identifier | Deletes the event definition. |
send() | event, contact_id OR email, payload | Triggers an event instance for a specific contact. |
Sources: resend/events/_events.py:165-240, examples/events.py:43-100
Sending Events
To track an occurrence of an event, you call the send() method. You must identify the target contact using either a contact_id or an email. The payload provided must align with the event's defined schema if one exists.
Sending Process
The sequence diagram illustrates the flow of triggering a custom event for a contact.
Sources: resend/events/_events.py:71-94, examples/events.py:73-90
Webhook Integration
The Events Tracking system interacts closely with Webhooks to provide real-time updates. When system-level or custom events occur, Resend delivers a WebhookEventPayload to your configured endpoints.
Webhook Event Types
Webhooks track several categories of events:
- Email Events:
email.sent,email.delivered,email.bounced,email.clicked,email.opened, etc. - Contact Events:
contact.created,contact.updated,contact.deleted. - System Events:
domain.created,topic.created,inbox.thread.created.
Sources: resend/webhooks/_webhooks.py:44-65, resend/webhooks/_webhook_event.py:840-877
Payload Verification
To ensure event data is authentic, you must verify the webhook signature using Webhooks.verify(). This method validates the HMAC-SHA256 signature against the raw payload and your signing secret.
# Example of manual verification logic
from resend import Webhooks
payload = '{"type":"email.sent", ...}'
headers = {"id": "msg_123", "timestamp": "1700000000", "signature": "v1,abc..."}
secret = "whsec_..."
event_data = Webhooks.verify({
"payload": payload,
"headers": headers,
"webhook_secret": secret
})
Sources: resend/webhooks/_webhooks.py:382-440, tests/webhooks_test.py:228-255
Data Structures
Event Schema Components
The system uses typed dictionaries to ensure consistency across the SDK.
# From resend/events/_event.py
class Event(TypedDict):
id: str
name: str
schema: Optional[EventSchema]
created_at: str
updated_at: Optional[str]
EventSchema = Dict[str, Literal["string", "number", "boolean", "date"]]
Sources: resend/events/_event.py:12-25, resend/events/_events.py:36-40
Webhook Event Metadata
When events are retrieved via the Webhooks API, they include delivery status information.
| Field | Type | Description |
|---|---|---|
id | str | The unique webhook event ID. |
type | WebhookEvent | The type of event (e.g., email.sent). |
status | str | Delivery status: pending, attempting, success, or failed. |
payload | dict | The actual event data payload. |
Sources: resend/webhooks/_webhooks.py:44-100
Summary
Events Tracking provides the infrastructure to monitor both custom application logic (via defined Events) and system-level operations (via Webhooks). By combining schema-validated event definitions with secure webhook delivery, you can build responsive, event-driven applications that react to user interactions and email delivery lifecycle changes.
Sources: resend/events/_events.py, resend/webhooks/_webhooks.py