Webhooks Infrastructure & Security
Relevant source files
The following files were used as context for generating this wiki page:
Webhooks Infrastructure & Security provides the mechanisms to receive, validate, and manage Resend webhooks within a .NET environment. The system ensures that incoming messages originate from Resend by verifying cryptographic signatures and provides a structured pipeline for handling different event types.
This module includes an API client for administrative tasks—such as creating endpoints and rotating secrets—and a server-side "Sink" architecture for processing incoming HTTP requests. The security layer relies on Svix-compatible headers to prevent spoofing and replay attacks.
Webhook Management API
The ResendClient implements methods to manage webhook configurations through the Resend API. You use these methods to programmatically control which URLs receive events and which event types are active.
Administrative Operations
The following table summarizes the primary management operations available:
| Operation | Method | Description |
|---|---|---|
| List Webhooks | WebhookListAsync | Retrieves a paginated list of all configured webhooks. |
| Create Webhook | WebhookCreateAsync | Registers a new endpoint URL and associated event types. |
| Retrieve Webhook | WebhookRetrieveAsync | Gets full details for a specific webhook, including the signing secret. |
| Update Webhook | WebhookUpdateAsync | Modifies the URL, status, or events of an existing webhook. |
| Delete Webhook | WebhookDeleteAsync | Removes a webhook configuration. |
| Rotate Secret | WebhookRotateSigningSecretAsync | Generates a new signing secret for an existing webhook. |
Sources: src/Resend/ResendClient.Webhooks.cs:8-76, tools/Resend.ApiServer/Controllers/WebhookController.cs:17-88
Event Log and Replay
Resend maintains a log of events and delivery attempts. You can query these logs or trigger a redelivery of a specific event.
- Event Retrieval:
WebhookEventRetrieveAsyncfetches details for a specific delivery event, including the JSON payload. - Attempt Tracking:
WebhookEventAttemptListAsynclists the HTTP status codes and responses for every delivery attempt. - Event Replay:
WebhookEventReplayAsyncrequests Resend to re-send a specific event to the configured endpoint.
Sources: src/Resend/ResendClient.Webhooks.cs:79-136, tools/Resend.ApiServer/Controllers/WebhookController.cs:115-182
Security and Validation
Security is enforced through signature verification on every incoming request. The WebhookValidator class handles the extraction of headers and the cryptographic check.
Validation Requirements
The validator requires three specific HTTP headers:
svix-id: A unique identifier for the webhook message.svix-timestamp: The Unix timestamp of the request.svix-signature: The HMAC signature used for verification.
Sources: src/Resend.Webhooks/WebhookValidator.cs:76-105
Validation Logic Flow
The following diagram illustrates how the WebhookValidator processes a request:
The system uses the Svix library to verify the payload against the signature using the configured WebhookValidatorOptions.Secret.
Sources: src/Resend.Webhooks/WebhookValidator.cs:33-149
Webhook Sink Architecture
The WebhookSink<T> provides a standardized entry point for processing validated webhooks. It separates the infrastructure concerns (reading the body, validating signatures) from the business logic (handling the event).
Execution Pipeline
The ExecuteAsync method orchestrates the following sequence:
- It calls the
WebhookValidatorto check the request integrity. - It populates a
WebhookContextwith the result. - If valid, it invokes
handler.HandleValid(ctx). - If invalid, it invokes
handler.HandleInvalid(ctx). - It catches unhandled exceptions and returns an Internal Server Error (500) while logging the failure.
Sources: src/Resend.Webhooks/WebhookSink.cs:20-56
Data Structures
The system uses several key classes to represent webhook state and data:
| Class | Purpose | Key Properties |
|---|---|---|
Webhook | Represents the persistent configuration. | Id, EndpointUrl, SigningSecret, Status, Events |
WebhookContext | Encapsulates the state of a single request. | MessageId, Payload, Event, IsValid, Exception |
WebhookData | Input model for management operations. | EndpointUrl, Status, Events |
WebhookEventDetails | Detailed view of a specific event instance. | Id, Type, Payload, Status, MomentNextAttempt |
Sources: src/Resend/Webhook.cs:8-44, src/Resend.Webhooks/WebhookContext.cs:5-32, src/Resend/WebhookData.cs:8-25, src/Resend/WebhookEventDetails.cs:10-46
Processing Flow Sequence
The interaction between the HTTP request, the Sink, the Validator, and the Application Handler is shown below:
Summary
Webhooks Infrastructure & Security provides a robust framework for integrating Resend event notifications into .NET applications. By centralizing signature verification in the WebhookValidator and execution flow in the WebhookSink, the system protects against malicious payloads while offering a clean interface for developers to implement custom event handlers. Management of these hooks is further simplified through a comprehensive set of client methods for endpoint administration and event log inspection.