> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailr.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Webhooks

> Use webhooks to notify your application about events from Emailr.

## What is a webhook?

Emailr 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](/docs/guides/dashboard/receiving/introduction)

## 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:

```js pages/api/webhooks.ts theme={null} theme={null}
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 Emailr that the event was successfully delivered.

<Tip>
  For development, you can create a tunnel to your localhost server using a tool like
  [ngrok](https://ngrok.com/download) or [VS Code Port Forwarding](https://code.visualstudio.com/docs/debugtest/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`
</Tip>

### 2. Add a webhook in Emailr.

Navigate to the [Webhooks page](https://app.emailr.dev/dashboard/webhooks) select **Add Webhook**.

1. Add your your publicly accessible HTTPS URL
2. Select all events you want to observe

<img alt="Screenshot placeholder" src="https://mintcdn.com/emailrdev/tSm2WeCvU8-lHmTx/images/placeholder.svg?fit=max&auto=format&n=tSm2WeCvU8-lHmTx&q=85&s=93891ced94bad8f8c38f90b5be99f73c" width="800" height="450" data-path="images/placeholder.svg" />

### 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:

```json theme={null} theme={null}
{
  "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 <onboarding@emailr.dev>",
    "to": ["delivered@emailr.dev"],
    "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.

<img alt="Screenshot placeholder" src="https://mintcdn.com/emailrdev/tSm2WeCvU8-lHmTx/images/placeholder.svg?fit=max&auto=format&n=tSm2WeCvU8-lHmTx&q=85&s=93891ced94bad8f8c38f90b5be99f73c" width="800" height="450" data-path="images/placeholder.svg" />

<Info>
  View all possible [event types and their webhook payload
  responses](/docs/guides/dashboard/webhooks/event-types).
</Info>

### 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:

```js pages/api/webhooks.ts theme={null} theme={null}

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 Emailr dashboard.

## FAQ

<AccordionGroup>
  <Accordion title="What is the retry schedule?">
    If Emailr 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.
  </Accordion>

  <Accordion title="What IPs do webhooks POST from?">
    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`
  </Accordion>

  <Accordion title="Can I retry webhook events manually?">
    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.
  </Accordion>
</AccordionGroup>

## Try it yourself

<Card title="Webhook Code Example" icon="arrow-up-right-from-square" href="https://github.com/emailr/emailr-examples/tree/main/with-webhooks">
  See an example of how to receive webhooks events for Emailr emails.
</Card>