---
title: Introduction
description: Use webhooks to notify your application about events from Reloop.
---
> For the complete documentation index, see [llms-docs.txt](/llms-docs.txt) or the site index [llms.txt](/llms.txt). Full docs corpus: [llms-full-docs.txt](/llms-full-docs.txt). Prefer markdown URLs (append `.md`) for agent consumption. Product skill: [skill.md](/skill.md).


Webhooks allow you to build or set up integrations which subscribe to certain events on Reloop. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.

## What is a webhook?

Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, such as an email being delivered or a domain being verified. When that event occurs, the source site makes an HTTP request to the URL configured for the webhook. Users can configure them to cause events on one site to invoke behavior on another.

## Why use webhooks?

- 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/webhooks/ingester)

## How to receive webhooks

### 1. Create a dev endpoint to receive requests.

Set up a URL on your server that can receive HTTP POST requests.

```javascript
export default (req, res) => {
  if (req.method === 'POST') {
    const event = req.body;
    console.log(event);
    res.status(200).send('OK');
  }
};
```

You can use tools like [ngrok](https://ngrok.com) or [VS Code Port Forwarding](https://code.visualstudio.com/docs/debugtest/port-forwarding) to expose your local server to the internet.

### 2. Add a webhook in Reloop.

Go to the [Webhooks page](https://app.reloop.sh/webhooks) in your dashboard.
1. Add your publicly accessible HTTPS URL.
2. Select all events you want to observe.

### 3. Test your local endpoint.

When you send an email or trigger an event, Reloop will send a payload like this to your endpoint:

```json
{
  "id": "whev_01h…",
  "type": "email.bounced",
  "created_at": "2026-07-22T23:41:12.126Z",
  "data": {
    "email_id": "em_123456789",
    "from": "Acme <onboarding@reloop.sh>",
    "to": ["bounced@reloop.sh"],
    "subject": "Sending this example",
    "status": "bounced",
    "error": {
      "code": 550,
      "message": "User unknown"
    }
  }
}
```

All `data` fields use **snake_case**. See [Event Types](/docs/webhooks/event-types) for the full catalog and per-category shapes.

Headers include `Reloop-Id`, `Reloop-Timestamp`, and `Reloop-Signature` for verification.

### 4. Update and deploy your production endpoint.

Once you've tested your logic, update your endpoint to handle specific event types and deploy it to your production server.

```javascript
export default (req, res) => {
  if (req.method === 'POST') {
    const event = req.body;
    if (event.type === "email.bounced") {
      // Handle bounce logic
    }
    res.status(200).send('OK');
  }
};
```

### 5. Register your production webhook endpoint

Update your webhook URL in the [Reloop Dashboard](https://app.reloop.sh/webhooks) with your production URL.

## FAQ

<AccordionGroup>
  <Accordion title="What is the retry schedule?">
    If your server returns a non-2xx response, we retry up to 7 attempts:
    - Immediate
    - 5 seconds
    - 5 minutes
    - 30 minutes
    - 2 hours
    - 5 hours
    - 10 hours
  </Accordion>

  <Accordion title="How do I verify authenticity?">
    Use your endpoint secret (`whsec_…`) to verify `Reloop-Signature`. See [Verify Webhooks Requests](/docs/webhooks/verify-webhooks-requests).
    - `54.148.139.208`
    - `2600:1f24:64:8000::/52`
  </Accordion>

  <Accordion title="What are the delivery guarantees?">
    Reloop guarantees "at-least-once" delivery of webhooks. Each webhook has a unique `reloop-id` (or Svix ID) header that you can use for idempotency to ensure you don't process the same event twice.
  </Accordion>

  <Accordion title="Do events arrive in order?">
    We do not guarantee that events will arrive in the order they occurred. For example, an `email.opened` event might arrive before an `email.delivered` event due to network latency or retries. You should use the `created_at` timestamp in the payload to order them.
  </Accordion>

  <Accordion title="Can I retry webhook events manually?">
    Yes, you can manually replay any failed or successful webhook event from the [Reloop Dashboard](https://app.reloop.sh/webhooks).
  </Accordion>
</AccordionGroup>

---

## Learn More

- [Event Types](/docs/webhooks/event-types)
- [Webhook Ingester](/docs/webhooks/ingester)
- [Verifying Requests](/docs/webhooks/verify-webhooks-requests)