Webhooks Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/webhooks/Webhooks.java
- src/main/java/com/resend/services/webhooks/model/WebhookEvent.java
- src/main/java/com/resend/services/webhooks/model/CreateWebhookOptions.java
- src/main/java/com/resend/services/webhooks/model/UpdateWebhookOptions.java
- src/main/java/com/resend/services/webhooks/model/VerifyWebhookOptions.java
- src/main/java/com/resend/services/webhooks/model/WebhookEventStatus.java
- src/main/java/com/resend/services/webhooks/dto/WebhookDTO.java
The Webhooks module manages HTTP callbacks that notify your application when specific events occur in Resend. This system allows you to register endpoints, subscribe to events, and verify the authenticity of incoming notifications to ensure they originated from Resend.
Sources: src/main/java/com/resend/services/webhooks/Webhooks.java, src/main/java/com/resend/services/webhooks/model/WebhookEvent.java
Core Webhook Management
The Webhooks class provides methods to create, update, retrieve, and delete webhook configurations. You use these methods to define which URL Resend should call and which events should trigger those calls.
Webhook CRUD Operations
The following table describes the primary management operations available:
| Operation | Method | Description |
|---|---|---|
| Create | create(CreateWebhookOptions) | Registers a new webhook endpoint and event subscriptions. |
| Update | update(String, UpdateWebhookOptions) | Modifies an existing webhook's endpoint, events, or status. |
| Get | get(String) | Retrieves full details of a specific webhook configuration. |
| List | list() / list(ListParams) | Returns a collection of configured webhooks. |
| Delete | remove(String) | Permanently removes a webhook configuration. |
Sources: src/main/java/com/resend/services/webhooks/Webhooks.java:54-156
Configuration Components
Webhook configurations consist of an endpoint URL, a set of trigger events, and a status.
- Endpoint: The HTTPS URL where Resend sends the POST request.
- Events: A list of
WebhookEventconstants (e.g.,EMAIL_SENT,EMAIL_BOUNCED). - Status: An indicator of whether the webhook is active or disabled.
Sources: src/main/java/com/resend/services/webhooks/model/CreateWebhookOptions.java:11-20, src/main/java/com/resend/services/webhooks/model/UpdateWebhookOptions.java:11-23
Webhook Events and Lifecycle
Resend triggers webhooks for various domain, email, and contact events. Each event follows a delivery lifecycle tracked by the system.
Trigger Events
The WebhookEvent enum defines all supported triggers:
| Category | Events |
|---|---|
email.sent, email.delivered, email.bounced, email.complained, email.clicked, email.opened, email.received, email.failed | |
| Contact | contact.created, contact.updated, contact.deleted, contact.topics.updated |
| Domain | domain.created, domain.updated, domain.deleted |
| Topic | topic.created, topic.updated, topic.deleted |
Sources: src/main/java/com/resend/services/webhooks/model/WebhookEvent.java:8-51
Delivery Monitoring
You can inspect the delivery status of individual events through the listEvents, getEvent, and listEventAttempts methods.
The diagram above shows the state transitions for a webhook event from occurrence to final status.
Sources: src/main/java/com/resend/services/webhooks/model/WebhookEventStatus.java:8-18, src/main/java/com/resend/services/webhooks/Webhooks.java:101-146
Security and Verification
To prevent unauthorized parties from sending fake events to your server, Resend signs every webhook request. You must verify these signatures using the verify method.
Verification Logic
The verification process uses an HMAC-SHA256 signature and a timestamp window to protect against timing and replay attacks.
- Extract Headers: Retrieve
svix-id,svix-timestamp, andsvix-signaturefrom the incoming request. - Validate Timestamp: Ensure the timestamp is within a 5-minute (300 seconds) tolerance window of the current time.
- Construct Payload: Concatenate
{id}.{timestamp}.{raw_payload}. - Compute Signature: Generate an HMAC-SHA256 hash using the signing secret (excluding the
whsec_prefix). - Compare: Perform a constant-time string comparison between the computed hash and the signature provided in the headers.
Sources: src/main/java/com/resend/services/webhooks/Webhooks.java:163-255
Verification Architecture
The sequence diagram illustrates the flow of a webhook request and the verification step performed by the SDK.
Sources: src/main/java/com/resend/services/webhooks/Webhooks.java:163-255, src/main/java/com/resend/services/webhooks/model/VerifyWebhookOptions.java:11-30
Secret Management
Every webhook has a unique signing_secret generated upon creation. If a secret is compromised, you can rotate it.
- Rotation: Use
rotateSigningSecret(webhookId)to generate a new secret. - Grace Period: The previous secret remains valid for 24 hours to prevent downtime during configuration updates.
Sources: src/main/java/com/resend/services/webhooks/Webhooks.java:128-135, src/main/java/com/resend/services/webhooks/model/CreateWebhookResponseSuccess.java:31-40
Summary
The Webhooks Configuration system provides a robust framework for handling asynchronous event notifications. It integrates management APIs for endpoint lifecycle, comprehensive event monitoring with status tracking, and a security-first verification mechanism using HMAC signatures and timestamp validation to ensure data integrity and authenticity.