Webhooks & Receiver Setup

Relevant source files

The following files were used as context for generating this wiki page:

• webhooks.go
• examples/webhooks.go
• examples/webhook_receiver.go
• webhooks_test.go
• CHANGELOG.md

The Webhooks service manages notification endpoints that receive real-time updates about email delivery, contact changes, and system events. This system allows you to register URLs that Resend calls when specific events occur within your project.

The implementation includes tools for endpoint management and a verification utility to ensure incoming requests originate from Resend. Use the WebhooksSvc interface to create, update, list, or delete webhook configurations and to verify payload signatures.

Sources: webhooks.go:103-130, CHANGELOG.md:19-20

Webhook Management

You manage webhook endpoints through the Webhooks service on the Resend client. Each webhook configuration defines a target URL and a list of events that trigger a notification to that URL.

Configuration and Lifecycle

When you create a webhook, Resend provides a signing_secret. You must store this secret to verify subsequent incoming notifications. The service supports rotating this secret if it becomes compromised.

The diagram shows the lifecycle of a webhook from creation to secret management.
Sources: webhooks.go:303-319, examples/webhooks.go:19-33

Supported Events

Webhooks support a wide range of events across different system modules.

Category	Event Constants
Email	email.sent, email.delivered, email.bounced, email.opened, email.clicked
Contact	contact.created, contact.updated, contact.deleted
Domain	domain.created, domain.updated, domain.deleted
Inbox	inbox.created, inbox.thread.created, inbox.email.received

Sources: webhooks.go:16-65

Webhook Receiver Setup

A receiver is an HTTP server endpoint in your application that processes POST requests from Resend. To ensure security, the receiver must validate the request payload using HMAC-SHA256 signature verification.

Verification Logic

Resend includes three specific headers with every webhook request: svix-id, svix-timestamp, and svix-signature. The verification process confirms that the payload has not been tampered with and that the request was sent within a valid time window.

The sequence diagram illustrates the synchronous verification flow within a receiver endpoint.
Sources: webhooks.go:338-410, examples/webhook_receiver.go:21-65

Implementation Steps

1. Read the raw request body as a string.
2. Extract the svix-id, svix-timestamp, and svix-signature headers.
3. Invoke the client.Webhooks.Verify method with the payload, headers, and your stored signing secret.
4. If verification succeeds, parse the JSON payload to process the event.
5. Return a 200 OK status to acknowledge receipt.

Sources: examples/webhook_receiver.go:30-74

Event Inspection and Replay

The SDK provides methods to inspect the history of events sent to a specific webhook and to retry deliveries if your receiver was unavailable.

Delivery Attempts

Each event tracks its delivery status and history. If an initial delivery fails, you can list the attempts to see the HTTP status codes and responses returned by your server.

Status	Description
pending	Event is waiting for a delivery attempt.
attempting	Event is currently being delivered.
success	Event was delivered and the receiver returned a 2xx code.
failed	Event delivery failed after all retry attempts.

Sources: webhooks.go:72-84, webhooks.go:162-167

Replaying Events

If your server missed an event, you can use the ReplayEvent method to queue a new delivery attempt for a specific event ID.
Sources: webhooks.go:264-278, examples/webhooks.go:111-115

Data Structures

Webhook Object

Represents the configuration of a webhook endpoint.
Sources: webhooks.go:103-111

Field	Type	Description
Id	string	Unique identifier for the webhook.
Endpoint	string	The URL that receives notifications.
Status	string	Current state (enabled or disabled).
Events	[]string	List of event types that trigger this webhook.
SigningSecret	string	Secret used for HMAC-SHA256 signature verification.

VerifyWebhookOptions

Parameters required to perform a manual verification.
Sources: webhooks.go:193-197

Parameter	Type	Description
Payload	string	The raw HTTP request body.
Headers	WebhookHeaders	Struct containing svix-id, svix-timestamp, and svix-signature.
WebhookSecret	string	The signing secret provided during webhook creation.

Conclusion

The Webhooks system provides a robust mechanism for reacting to asynchronous events in the Resend ecosystem. By combining the management API with the manual verification utility, you can build secure and reliable integrations that stay synchronized with your email and contact data.

Sources: webhooks.go:1-415