Webhook Management
Relevant source files
The following files were used as context for generating this wiki page:
Webhook Management handles the registration, configuration, and security verification of webhook endpoints within the Resend ecosystem. This system allows your application to receive real-time notifications about email events, such as when an email is sent, delivered, or bounced.
The management interface provides tools to perform CRUD operations on webhook resources, track event delivery history through attempts, and ensure the authenticity of incoming requests using cryptographic signatures.
Webhook Service Operations
The Resend\Service\Webhook class manages the lifecycle of webhook resources. It interacts with the Resend API to configure where events are sent and which specific event types trigger a notification.
Core Management Methods
The service supports the following primary actions:
- Create: Registers a new endpoint and subscribes it to specific events.
- List: Retrieves all configured webhooks for the account.
- Get: Fetches the details of a specific webhook by its ID.
- Update: Modifies the status or configuration of an existing webhook.
- Remove: Deletes a webhook resource.
- Rotate Signing Secret: Generates a new security secret for a webhook, invalidating the previous one.
Sources: src/Service/Webhook.php:21-98
Resource Data Model
The Resend\Webhook class represents the data structure of a webhook resource.
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier for the webhook. |
object | string | Type of object (always "webhook"). |
created_at | string | Timestamp of creation. |
status | string | Current state (e.g., "enabled"). |
endpoint | string | The URL receiving the events. |
events | array | List of subscribed event types (e.g., email.sent). |
signing_secret | string | The secret used for signature verification. |
Sources: src/Webhook.php:5-18, tests/Fixtures/Webhook.php:5-15
Webhook Signature Verification
Security verification ensures that incoming HTTP requests originate from Resend and have not been tampered with. The Resend\WebhookSignature class implements the verification logic using HMAC SHA256 signatures and timestamp validation.
Verification Flow
The verification process requires three specific headers typically prefixed with svix-:
- svix-id: A unique message identifier.
- svix-timestamp: The Unix timestamp of the request.
- svix-signature: One or more versioned signatures (e.g.,
v1,signature_hash).
The system validates that the timestamp falls within a specific tolerance (defaulting to 300 seconds) to prevent replay attacks. It then generates an expected signature using the raw request payload, the ID, and the timestamp, comparing it against the provided signature header.
Sources: src/WebhookSignature.php:9-48
Signature Logic Diagram
The following diagram illustrates the logical steps taken by the verify method to authenticate a request.
The diagram shows the validation sequence for incoming webhook payloads.
Sources: src/WebhookSignature.php:11-54
Webhook Events and Delivery Attempts
Every notification sent to a webhook is tracked as an Event. Each event can have multiple EventAttempts if the initial delivery fails.
Event Object Structure
The Resend\Webhooks\Event resource contains the actual data payload delivered to the endpoint.
| Field | Description |
|---|---|
id | The unique identifier for the event. |
type | The event category (e.g., email.delivered). |
status | Delivery status (e.g., success). |
payload | The actual JSON data containing email details. |
next_attempt_at | The scheduled time for a retry if the previous one failed. |
Sources: src/Webhooks/Event.php:7-17, tests/Fixtures/Webhook.php:48-69
Event Management Flow
The Resend\Service\Webhooks\Event service provides methods to list historical events for a specific webhook or replay a specific event.
The sequence diagram demonstrates how the client interacts with event history and triggers replays.
Sources: tests/Service/Webhook.php:41-80
Implementation Example
The verify method provides a convenient wrapper around the WebhookSignature logic.
// Verifying an incoming webhook request
$payload = file_get_contents('php://input');
$headers = getallheaders();
$secret = 'whsec_xxxxxxxxxx';
try {
$isValid = $resend->webhooks->verify($payload, $headers, $secret);
// Process the event if valid
} catch (WebhookSignatureVerificationException $e) {
// Handle invalid signature
}
Sources: src/Service/Webhook.php:103-106, tests/Service/Webhook.php:115-121
Summary
Webhook Management provides a comprehensive suite for integrating real-time email event notifications. By utilizing the Webhook service for resource management and the WebhookSignature class for security, developers can build robust systems that react to email lifecycle changes while maintaining high security standards. The system's ability to track delivery attempts and replay events ensures data consistency even during network or application failures.