> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/developers/webhooks/using-webhooks.md).

# Using Webhooks

You can use webhooks in Limio to trigger automated actions in your own systems when specific Events occur - such as a new order, cancellation, or subscription update.

Limio sends the full object data in the JSON body, allowing your system to process it in real time. You can find the list of objects we generated webhooks for [here](/developers/webhooks/overview.md).

### Why use webhooks?

Webhooks are designed for **asynchronous** communication and background tasks. They allow Limio to trigger external actions automatically when specific actions or events occur.

Common use cases include:

* **Integrating with third-party platforms** like fulfillment systems or entitlement providers to ensure downstream systems are updated when a subscription changes.
* **Sending event data to a data warehouse** to support customer profiling, segmentation, churn prediction, and other analytics.

> For **synchronous use cases** that require an immediate response (e.g. validating customer eligibility during order submission), consider using a synchronous [Callout Plugin](https://docs.limio.com/integrations/order-orchestration/callout-plugin) webhook.

### How to configure a webhook in Limio

To set up a webhook:

1. Go to **Settings > General Settings > Webhooks**
2. For each webhook type you want to track, enter the **destination URL** where Limio should send the webhook
3. (Optional) Configure authentication if required by your receiving system

> 📘 **Example webhook endpoint:**\
> `https://your-domain.com/your-endpoint`

### Authenticating webhooks

If your endpoint requires authentication, you can configure **Basic Authentication**:

1. Go to Settings > Authentication Provider and, select **Basic Auth** as the authentication method
2. Provide:
   * **Name**: The **hostname** of the destination endpoint.\
     \&#xNAN;*For example, if your webhook URL is `https://example-site.com/my-webhook`, enter `example-site.com`.*
   * **Username** and **Password**: The credentials required by your endpoint

Limio will include an `Authorization` header in each request using these credentials.

### Webhook payload format

Each webhook is sent as an HTTP POST request with a **JSON body**. The payload includes the object that triggered the webhook — for example, an order or subscription. You can inspect webhook payloads in **Subscriptions > Webhooks** in the Limio UI to see the exact data structure sent for each event type.

This allows your system to process the data contextually.

Limio sends **raw JSON**. It does not transform the payload to match the expected format of specific third-party tools (e.g. Slack, Microsoft Teams, or other messaging platforms). If you need to forward webhook events to such tools, you will need a small middleware layer (e.g. AWS Lambda, n8n, Zapier, or Make) that receives the Limio webhook, formats the payload, and forwards it.

### What happens when a webhook fails?

> ⚠️ Limio does **not** retry failed webhooks. If your endpoint is unreachable or returns a 4xx/5xx response, the event is not resent automatically.

There are three ways to handle this:

**1. Use the Error webhook for alerting**

Configure an Error webhook (Settings > General Settings > Webhooks > Error Reporting) to receive a notification whenever an order processing failure occurs. This lets your middleware trigger a recovery workflow rather than waiting to discover the failure.

**2. Inspect failed payloads in the Limio UI**

Failed webhook deliveries are logged in the Limio interface. Navigate to **Subscriptions > Webhooks** (or `https://[your-limio-domain]/objects/webhooks/limio`) to find the failed payload and replay it manually if needed.

**3. Poll via the Limio Object API**

As a fallback, your middleware can query the [Limio Object API](https://developers.limio.com) to retrieve order or subscription data directly using the known object ID — useful if the original webhook payload was never received.

### Viewing webhook activity

You can monitor webhook deliveries from the Limio UI:

* Go to **Subscriptions > Webhooks**
* Or access directly via:\
  `https://[your-limio-domain]/objects/webhooks/limio`

This view lets you inspect:

* Webhook status (success or failure)
* Webhook timestamps
* JSON payloads

### Configure webhook timeouts and failure notifications

You now define how long Limio waits for a webhook to respond and receive notifications when a webhook fails. These settings apply to **all webhooks** triggered by Limio. Navigate to Settings > General Settings > Webhooks to configure the following:

**1. Set webhook timeout duration**

Control how long Limio waits for a response from your webhook endpoint. Timeout is defined in milliseconds.

* **Default timeout**: 2000 milliseconds (2 seconds)
* **Custom timeout**: You can set a different value to suit your system's performance.

> 📘 **Tip:** Use short timeouts (2–5 seconds) to prevent delays in Limio processing if your webhook endpoint is slow or unresponsive.

**2. Receive email alerts on webhook failures**

You can configure an email address to be notified when a webhook fails. This ensures you're aware of failures and can act quickly.

Failures include:

* Endpoint does not respond within the timeout window
* The webhook request returns a 4xx or 5xx status code

> 📤 The alert email contains details of the failed webhook, including the webhook type and error response. To test, set your email, then either point the webhook you are testing at a dummy endpoint or set a very low timeout (for example `1` millisecond), and process an order or change. Setting the timeout to `0` will **not** force a timeout: a value of `0` is ignored and Limio falls back to the 2000 millisecond default.

<figure><img src="/files/wGro7x3FQAvW1iYUM5wG" alt=""><figcaption><p>Webhooks Settings in Limio</p></figcaption></figure>

### IP range

The following IP ranges are used by Limio services

| Service       | IP Range       |
| ------------- | -------------- |
| Webhooks (EU) | 18.184.42.235  |
| Webhooks (NA) | 54.205.175.178 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.limio.com/developers/webhooks/using-webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.