Skip to main content

​
What is a webhook?

Resend uses webhooks, which are real-time HTTPS requests that tell your application an event occurred, such as an email delivery notification or subscription status update.

​
Why use webhooks?

All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:
  • Automatically remove bounced email addresses from mailing lists
  • Create alerts in your messaging or incident tools based on event types
  • Store all send events in your own database for custom reporting/retention
  • Receive emails using Inbound

​
How to receive webhooks

To receive real-time events in your app via webhooks, follow these steps:

​
1. Create a dev endpoint to receive requests.

In your local application, create a new route that can accept POST requests. For example, you can add an API route:
pages/api/webhooks.ts
export default (req, res) => {
  if (req.method === 'POST') {
    const event = req.body;
    console.log(event);
    res.status(200);
  }
};
On receiving an event, you should respond with an HTTP 200 OK to signal to Resend that the event was successfully delivered.
For development, you can create a tunnel to your localhost server using a tool like ngrok or VS Code Port Forwarding. These tools serve your local dev environment at a public URL you can use to test your local webhook endpoint.Example: https://example123.ngrok.io/api/webhook

​
2. Add a webhook in Resend.

Navigate to the Webhooks page select Add Webhook.
  1. Add your your publicly accessible HTTPS URL
  2. Select all events you want to observe
Add Webhook

​
3. Test your local endpoint.

To ensure your endpoint is successfully receiving events, perform an event you are tracking with your webhook, like sending an email, creating a contact, or creating a domain. The webhook will send a JSON payload to your endpoint with the event details. For example: 
{
  "type": "email.bounced",
  "created_at": "2024-11-22T23:41:12.126Z",
  "data": {
    "broadcast_id": "8b146471-e88e-4322-86af-016cd36fd216",
    "created_at": "2024-11-22T23:41:11.894719+00:00",
    "email_id": "56761188-7520-42d8-8898-ff6fc54ce618",
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Sending this example",
    "template_id": "43f68331-0622-4e15-8202-246a0388854b",
    "bounce": {
      "message": "The recipient's email address is on the suppression list because it has a recent history of producing hard bounces.",
      "subType": "Suppressed",
      "type": "Permanent"
    },
    "tags": {
      "category": "confirm_email"
    }
  }
}
You can also see the webhook details in the dashboard. Webhook Events List
View all possible event types and their webhook payload responses.

​
4. Update and deploy your production endpoint.

Once you successfully receive events, update your endpoint to process the events. For example, update your API route:
pages/api/webhooks.ts

export default (req:, res) => {
  if (req.method === 'POST') {
    const event = req.body;
    if(event.type === "email.bounced"){
      //
    }
    res.status(200);
  }
};
After you’re done testing, deploy your webhook endpoint to production.

​
4. Register your production webhook endpoint

Once your webhook endpoint is deployed to production, you can register it in the Resend dashboard.

​
FAQ

If Resend does not receive a 200 response from a webhook server, we will retry the webhooks.Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:
  • 5 seconds
  • 5 minutes
  • 30 minutes
  • 2 hours
  • 5 hours
  • 10 hours
You can see when a message will be retried next in the webhook message details in the dashboard.
If your server requires an allowlist, our webhooks come from the following IP addresses:
  • 44.228.126.217
  • 50.112.21.217
  • 52.24.126.164
  • 54.148.139.208
  • 2600:1f24:64:8000::/52
Yes. You can retry webhook events manually from the dashboard.To retry a webhook event, click to see your webhook details and then click the link to the event you want to retry.On that page, you will see both the payload for the event and a button to replay the webhook event and get it sent to the configured webhook endpoint.

​
Try it yourself

Webhook Code Example

See an example of how to receive webhooks events for Resend emails.