Introduction

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

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.

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 or VS Code Port Forwarding to expose your local server to the internet.

2. Add a webhook in Reloop.

Go to the Webhooks page in your dashboard.

Add your publicly accessible HTTPS URL.
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:

{
  "type": "email.bounced",
  "created_at": "2023-11-22T23:41:12.126Z",
  "data": {
    "email_id": "em_123456789",
    "from": "Acme <onboarding@reloop.dev>",
    "to": ["delivered@reloop.dev"],
    "subject": "Sending this example",
    "bounce": {
      "message": "The recipient's email address is on the suppression list.",
      "subType": "Suppressed",
      "type": "Permanent"
    }
  }
}

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.

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 with your production URL.

FAQ

What is the retry schedule?

If your server returns an error, we retry with exponential backoff:

5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours

What IPs do webhooks POST from?

Webhooks are sent 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

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.

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.

Can I retry webhook events manually?

Yes, you can manually replay any failed or successful webhook event from the Reloop Dashboard.