Webhooks & Local Listener
Relevant source files
The following files were used as context for generating this wiki page:
Webhooks enable real-time event notifications from the Resend platform to an HTTPS endpoint. The Resend CLI provides a management suite to create, update, and list these endpoints, as well as a local listener tool to receive and inspect events during development.
Sources: src/commands/webhooks/index.ts:13-14, skills/resend-cli/references/webhooks.md:1-5
Webhook Management
The CLI manages the lifecycle of webhook endpoints. Each webhook delivers notifications for specific event categories including Email, Contact, Domain, Suppression, Topic, and Inbox.
Subscribing to Events
Users subscribe to specific events or all 37 available types. When creating or updating a webhook, the --events flag accepts a space or comma-separated list of event names. The all keyword acts as a shorthand for the complete event set.
Sources: src/commands/webhooks/create.ts:24-52, src/commands/webhooks/update.ts:22-29
Webhook Configuration Operations
The following table describes the primary management commands:
| Command | Action | Key Parameters |
|---|---|---|
create | Registers a new HTTPS endpoint | --endpoint, --events |
update | Modifies existing settings | --endpoint, --events, --status |
list | Displays registered webhooks | --limit, --after, --before |
get | Retrieves full webhook details | <id> |
delete | Removes a webhook | <id>, --yes |
rotate-signing-secret | Generates a new secret | <id> |
Sources: skills/resend-cli/references/webhooks.md:1-70, src/commands/webhooks/list.ts:11-19
Local Webhook Listener
The listen command facilitates local development by creating a temporary bridge between the Resend API and a local environment.
Operational Logic
The listener performs five primary actions:
- Starts a local HTTP server on a specified port (default 4318).
- Registers a temporary Resend webhook pointing at a provided public tunnel URL (e.g., ngrok).
- Displays incoming event details, including type, resource ID, and specific metadata.
- Forwards payloads to a local application URL if the
--forward-toflag is set. - Deletes the temporary webhook automatically upon process termination (Ctrl+C).
Sources: src/commands/webhooks/listen.ts:143-156, skills/resend-cli/references/webhooks.md:118-132
Local Listener Data Flow
This diagram illustrates how the CLI mediates between the Resend API and your local development server.
The CLI preserves original Svix headers (svix-id, svix-timestamp, svix-signature) when forwarding to the local application to allow for signature verification testing.
Sources: src/commands/webhooks/listen.ts:11-13, src/commands/webhooks/listen.ts:109-122, src/commands/webhooks/listen.ts:208-223
Event Summarization
The listener extracts relevant details from raw JSON payloads to provide readable console output.
| Category | Summary Detail Extracted |
|---|---|
Sender and first recipient (from -> to) | |
| Domain/Topic | Resource name |
| Contact/Suppression | Email address |
| Inbox | Subject lines or email addresses based on sub-type |
Sources: src/commands/webhooks/listen.ts:44-93
Signature Verification
Resend signs webhook payloads using Svix. Each delivery includes the svix-id, svix-timestamp, and svix-signature headers.
Security and Rotation
Webhooks return a signing_secret upon creation or retrieval. If a secret is compromised, the rotate-signing-secret command generates a new one. To prevent service interruption, Resend signs payloads with both the old and new secrets for a 24-hour transition period.
Sources: src/commands/webhooks/index.ts:33-37, skills/resend-cli/references/webhooks.md:65-70
Delivery History and Replay
The CLI provides tools to inspect past deliveries and troubleshoot failures.
The attempts command specifically helps debug by showing the exact http_status_code and response body returned by the user's endpoint.
Sources: skills/resend-cli/references/webhooks.md:86-116
Event Status Values
Events tracked in the delivery history transition through several states:
pending: Event is queued for delivery.attempting: Delivery is currently in progress.success: Endpoint returned a 2xx status code.failed: Retries are exhausted or a terminal error occurred.
Sources: skills/resend-cli/references/webhooks.md:84, src/commands/webhooks/listen.ts:101-105
Summary
The Webhooks and Local Listener systems provide a complete workflow for integrating real-time notifications. Developers can manage production endpoints through standard CRUD commands and use the local listener to simulate and debug webhook integrations without manual configuration of permanent endpoints or complex tunneling setups.