Use incoming webhooks to get real-time updates

Listen for events on your Mailabl account so your integration can automatically trigger reactions.

They work by sending out an HTTP request to a specified endpoint when an event is triggered. This makes webhooks ideal for integrating two applications.

Webhooks are a performant alternative to continuously polling for changes. Webhooks remove the need to send requests over and over. Instead, the service provider sends notifications whenever updated data it available.

How we use webhooks​

A webhook enables Mailabl to push real-time notifications to your endpoint as a JSON payload. You can then use these notifications to execute actions in your backend systems.

How to receive webhooks​

1. Create a webhook endpoint as an HTTP endpoint (URL) on your server.
2. Handle requests by parsing each event object and returning 2xx response status codes.
3. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
4. Register your publicly accessible HTTPS URL in the Settings > Integrations section.

Step 1: Create a webhook endpoint​

Set up an HTTP endpoint on your server that can accept unauthenticated webhook requests with a POST method and expects data to be delivered n a JSON payload.

Step 2: Handle requests​

Mailabl sends events to your webhook endpoint as part of a POST request with a JSON payload.

Check event objects​

Each event is structured as an event object with an id, type, occurredAt timestamp and related resource nested under data. Your endpoint must check the event type and parse the payload of each event.

[
  {
    "id": "256a5a1f-3c1f-4a87-9e37-0008be001ade",
    "type": "task.updated",
    "data": {
      "object": {
        "id": "9",
        "type": "task"
      }
    },
    "occurredAt": "2023-07-09T10:52:24.000000Z"
  }
]

As shown above, you should expect to receive an array of objects in a single request.

Return a 2xx response​

Your endpoint must quickly return a successful HTTP status code (2xx) prior to any complex logic that could cause a timeout.

Verify requests​

To ensure that the requests you're getting at your webhook endpoint are actually coming from Mailabl, Mailabl populates a X-Mailabl-Signature header with a SHA-256 hash of the concatenation of the app-secret for your application and the body of the webhook request.

Learn more about validating signature requests.

Retries​

If your server has problems handling notifications at any time, Mailabl will attempt to re-send failed notifications up to 10 times.

If a 2xx HTTP status code isn't received within 3 seconds or a status code other than 2xx is returned, we assume that the delivery is unsuccessful. We'll retry the delivery of the event notification using exponential backoff for up to 10 times after the originating event. After a 10th failed attempt, the notification is discarded.

Mailabl uses exponential backoff to avoid spamming applications and retries notifications according to the following schedule. For example, if we don't receive a 2xx status code 3 seconds after the event notice is received, Mailabl sends another notice of the event in 100 seconds. If no 2xx status code is received in 3 seconds, Mailabl tries again to send the event notice in about 16 minutes. The retry pattern is as follows:

Limitations​

• The webhooks API provides "at least once" delivery of webhook events. This means that an endpoint might receive the same webhook event more than once. You can detect duplicate webhook events by comparing the id field to previous events.
• Webhook delivery isn't always guaranteed. You should therefore implement reconciliation jobs to fetch data from Mailabl periodically.
• There's no guarantee of the delivery order of event notices.
• In most cases, event notifications arrive in well under 60 seconds of the associated event.
• Mailabl does not guarantee that you'll receive these notifications in the order they occurred. Use the occurredAt property for each notification to determine when the event that triggered the notification occurred.