# 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 does **not** retry failed webhooks. Ensure your endpoint is highly available and responds within the configured timeout window.

### 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, set the timeout to 0 or set a dummy endpoint for the webhook you are testing, and process an order or change.

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

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

The question should be specific, self-contained, and written in natural language.
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.