> 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/overview.md).
# Webhooks Overview
### Types of webhooks
Limio's webhooks will send the following object:
* Customer
* Subscription
* Order
* Entitlement
* Events
* Error Reporting
### Customer
#### Customer Created / Updated
This webhook sends the Limio Customer object whenever a customer is created or updated as part of a new subscription, either through Limio Commerce or Limio for Salesforce.
Example Customer webhook payload
```json
{
"data": {
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"addresses": [
{
"id": "addr-123abc",
"type": "billing",
"country": "GB",
"city": "London",
"postalCode": "SW1A 1AA",
"address1": "10 Downing Street",
"address2": "",
"state": ""
}
]
},
"status": "active",
"record_type": "customer",
"owner": "id-39e4c3727b273ec4110b5769c10cdb52",
"id": "cus-3578da83e3e4f12dff39b314bb486ca6",
"service": "limio",
"created": "2024-02-12T17:27:50.087Z",
"updated": "2024-02-12T17:27:54.005Z",
"reference": "CUST-REF-001",
"mode": "production"
}
```
### Subscription
#### Subscription Created
This webhook is used to receive the Subscription object after a Subscription gets created using the Limio Shop, Limio Self-Service or the Limio for Salesforce.
Example Subscription webhook payload
```json
{
"name": "2TJ25TK632EG",
"start": "2024-02-12",
"data": {
"offers": [
{
"name": "Standard Monthly",
"path": "/offers/standard-monthly",
"quantity": 1
}
],
"owner": "id-62401f8d5bf6b26a37ea0defd66fd005",
"schedule": [
{
"start": "2024-02-12",
"end": "2024-03-12",
"order_id": "order-4dd195c3eee4297e33aecb5436cf8092"
}
]
},
"status": "active",
"record_type": "subscription",
"owner": "id-62401f8d5bf6b26a37ea0defd66fd005",
"customer": "cus-3578da83e3e4f12dff39b314bb486ca6",
"id": "sub-02ecc45ed0c313a8dc4dd84c45854796",
"service": "limio",
"ref": "order-4dd195c3eee4297e33aecb5436cf8092/bc371cb3-43a9-1c83-722a-b56eeb212dbb",
"created": "2024-02-12T17:27:50.087Z",
"updated": "2024-02-12T17:27:54.005Z",
"reference": "2TJ25TK632EG",
"mode": "production"
}
```
### Order
The Order webhook is sent when the user goes through the actions described below (address change, payment method change, subscription offer change...).
Unlike the Customer and Subscription webhooks, the Order webhook does **not** wrap the order in a `data` envelope. The order's fields are sent at the top level, alongside:
* `owner` the identity that owns the order
* `name` and `orderReference` both hold the order reference, and are the same value
* `identities` any other identities linked to the owner, with the subject and issuer only
There is no object `id` on this payload. Use `name` (or `orderReference`) to identify the order.
Example Order webhook payload
```json
{
"email": "user@domain.com",
"tracking": {
"offers": ["/offers2/$75 for 52 weeks then $31.96 every 4 weeks autorenew"],
"purchaseCountryCode": "GB",
"accountId": "0017x00000Q9O9qAAF",
"contactId": "0037x00000F58M9AAJ",
"userId": "0057x0000088Oh3AAE"
},
"country": "GB",
"billingDetails": {
"country": "GB",
"firstName": "First",
"lastName": "Last",
"streetName": "Street",
"city": "City",
"address1": "Address 1",
"address2": "Address 2",
"postalCode": "SW1A 1AA",
"buildingNumber": 1,
"company": "Company",
"state": "State"
},
"__spec_version": "2",
"external_id": "1HPJ18UUJRV",
"source": "limio",
"orderItems": [
{
"offer": {
"name": "Standard Monthly",
"path": "/offers/standard-monthly"
},
"quantity": 1,
"price": {
"summary": {
"headline": "$75 for first year
"
},
"currency": "USD",
"amount": 75
},
"name": "$75 for 52 weeks then $31.96 every 4 weeks autorenew",
"id": "bdc3cfb7-77b9-d8b8-7395-f44758ef1b29",
"startDate": "2024-03-22",
"products": [
{
"name": "Digital Access",
"path": "/products/digital-access"
}
]
}
],
"process_immediately": true,
"mode": "production",
"total": {
"currency": "USD",
"amount": 75
},
"payment": {
"type": "invoice",
"invoicePref": "Email"
},
"customerDetails": {
"lastName": "Last",
"firstName": "First",
"email": "user@domain.com"
},
"sourceDetails": {
"instance": "env.scratch.my.salesforce.com"
},
"initiated_source": "salesforce",
"orderDate": "2024-03-22T12:13:28.026Z",
"order_type": "new",
"owner": "id-39e4c3727b273ec4110b5769c10cdb52",
"name": "2JTPIUPFQCQ0",
"orderReference": "2JTPIUPFQCQ0",
"identities": [
{
"sub": "8f1c2b0e-1f4a-4f77-9a2b-6f5d2c9a1b34",
"iss": "https://auth.example.com/",
"service": "limio",
"type": "user"
}
]
}
```
#### **Address Change**
This webhook is used to receive the Order object after the Address gets updated using the Limio Shop or Limio Self-Service functionalities.
#### Payment Method Change
This webhook is used to receive the Order object after the Payment Method gets updated using Limio Self-Service functionalities or Limio for Salesforce.
#### Subscription Offer Change
This webhook is used to receive the Order object after the Subscription Offer gets updated, usually during a switch scenario in Limio Self-Service or Limio for Salesforce.
#### Subscription Offer Addition
This webhook is used to receive the Order object after a new Subscription Offer is added, usually during a cancel/save scenario in Limio Self-Service or Limio for Salesforce.
#### Subscription Cancellation
This webhook is used to receive the Order object after the Subscription is cancelled, usually during a cancellation scenario in Limio Self-Service or Limio for Salesforce
#### Order Submitted
This webhook is used to receive the Order object after the Order is submitted by the customer using the Limio Shop.
#### Update Customer Details
This webhook is used to receive the Order object after the Customer Details gets updated using Limio Self-Service.
### Plugin-specific Webhooks
#### Amend Order Created
This webhook is used to receive the Amended Order object after one gets created using the Limio Shop or Limio Self-Service. It can only be used if the Zuora Rate Plan ID Plugin is enabled.
### Entitlement
#### Entitlements Updated
The entitlement webhook notifies external systems when entitlements have been updated. [Read more about how entitlements work in Limio](https://docs.limio.com/product/pricing/how-to-create-and-propagate-entitlements-with-limio)
It is sent for two groups of order types:
* **Entitlements granted.** For `new`, `change_offer` and `add_offer` orders, the `entitlements` array holds the entitlement codes the subscription now has.
* **Entitlements removed.** For `suspend` and `cancel_subscription` orders, the same webhook is sent with an **empty** `entitlements` array, and without `effectiveDate`. Treat an empty array as "this owner now has no entitlements from this subscription".
The subscription the change relates to is in `tracking.subscription`, and the order that caused it is in `tracking.name` / `tracking.orderReference`. Each item in `entitlements` carries only its `code`.
Example Entitlement webhook payload
```json
{
"tracking": {
"subscription": "2TJ25TK632EG",
"source": "limio",
"name": "7PKAAZR1EKEF0",
"orderReference": "7PKAAZR1EKEF0"
},
"effectiveDate": "2024-02-13T14:14:56.403Z",
"updated": "2024-02-13T14:14:56.403Z",
"owner": "id-62401f8d5bf6b26a37ea0defd66fd005",
"entitlements": [
{
"code": "digital_access"
}
]
}
```
Example Entitlement webhook payload on suspend or cancellation
```json
{
"tracking": {
"subscription": "2TJ25TK632EG",
"source": "limio",
"name": "7PKAAZR1EKEF0",
"orderReference": "7PKAAZR1EKEF0"
},
"updated": "2024-03-13T09:02:11.114Z",
"owner": "id-62401f8d5bf6b26a37ea0defd66fd005",
"entitlements": []
}
```
### Events
### Custom data in webhooks
When an order is submitted, you can pass a `customFields` object in the order request body. These fields are **not** stored as top-level fields on the resulting webhook payload — they are accessible via the `tracking` object in the order event data and on the resulting Order object.
Fields added or modified in Zuora (e.g. custom Zuora fields such as `SalesScenario__c`) are **not** propagated back into Limio webhooks. Limio does not read Zuora custom field values back into the webhook payload.
If you need to carry custom metadata through the order and into your downstream systems:
* Pass it in the `tracking` object of the order request — this flows through to the webhook payload.
* Or retrieve it via the [Limio Object API](https://developers.limio.com) after the order completes, using the order reference from the webhook (`name`, also sent as `orderReference`) as your reference.
***
#### Checkout Initiated
This webhook is used to receive the Event object after the Checkout is initiated by the customer using the Limio Shop.
> 📝 At this stage, `customerDetails.email` is typically **not yet populated** — the customer may not have authenticated. Use the [Abandoned Basket API](https://docs.limio.com/guides/developer-guides/guide-abandoned-basket) to retrieve email and user details once the customer authenticates.
Example Checkout Initiated webhook
```json
{
"data": {
"message": "Customer initiated the checkout",
"type": "checkout.initiated",
"event": {
"context": {
"client_ip": "string",
"identity_id": "string",
"cognitoIdentityId": null,
"requestContext": {
"resourceId": "string",
"resourcePath": "string",
"httpMethod": "string",
"extendedRequestId": "string",
"requestTime": "07/Mar/2023:12:58:39 +0000",
"path": "string",
"accountId": "string",
"protocol": "string",
"stage": "string",
"domainPrefix": "string",
"requestTimeEpoch": number,
"requestId": "string",
"identity": {
"cognitoIdentityPoolId": null,
"accountId": null,
"cognitoIdentityId": null,
"caller": null,
"sourceIp": "string",
"principalOrgId": null,
"accessKey": null,
"cognitoAuthenticationType": null,
"cognitoAuthenticationProvider": null,
"userArn": null,
"userAgent": "string",
"user": null
},
"domainName": "string",
"apiId": "string"
}
},
"basket": {
"basketItems": [
Offer
],
"chooseDate": false,
"hasDelivery": false,
"isGift": false,
"isRedeem": false
},
"order": {
"variant": "string",
"orderItems": [
{
"id": "string",
"name": "string",
"details": "",
"price": {
"currency": "string",
"amount": number,
"summary": {
"headline": "string",
"subline": "string"
}
},
"offer": Offer,
"products": [ Product ]
}
],
"external_id": "string",
"total": { "currency": "string", "amount": number },
"allowedCountries": ["string"],
"hasDelivery": false,
"isGift": false,
"isRedeem": false,
"chooseDate": false,
"redirectState": null,
"redirectUrl": null,
"subId": null,
"subRef": null,
"checkoutId": "string",
"tracking": { "offers": ["string"] },
"order_type": "new",
"subscriptionId": null,
"subscriptionReference": null
},
"tracking": { "offers": ["string"] },
"path": "string",
"completed": false
}
},
"status": "submitted",
"record_type": "event",
"related": "string",
"id": "string",
"service": "limio",
"created": datetime,
"updated": datetime,
"reference": "string",
"external_correlator": "string",
"mode": "production"
}
```
#### Cancel Attempted
This webhook is used to receive the Event object after the Customer attempted to cancel the subscription.
#### Payment Method Added
This webhook is used to receive the Event object after a Payment Method is added by the customer using the Limio Shop.
#### Address Added
This webhook is used to receive the Event object after an Address is added by the customer using the Limio Shop.
### Error Reporting
The **Error** webhook is used to notify you when a failure occurs during order processing in Limio. It provides visibility into issues across any step of the order orchestration pipeline and can be used to alert external systems or trigger recovery workflows. This can be useful to catch **payment failures**, which are the most typical type of failures.
#### When is this Error webhook fired?
When a customer places an order in Limio, it is handled by the [Order Orchestration Framework](https://docs.limio.com/integrations/order-orchestration/order-orchestration-framework). This framework breaks down the order into a series of processing steps handled by plugins, such as:
* Zuora (e.g. subscription and payment creation)
* Salesforce (e.g. contact creation)
* Entitlement or delivery logic
* Internal Limio plugins (e.g. gift redemption, Callout Plugin)
If any of these plugins fails, Limio generates an **Error webhook**. The Error webhook allows you to capture these failures externally for alerting, logging, or further action.
#### How to configure
1. Go to **Settings > General Settings > Webhooks**
2. Under **Error Reporting**, locate the **Error** field
3. Enter the destination URL where the webhook should be sent
Limio will send a POST request to this URL whenever a plugin fails during order processing.
#### Payload structure
Each POST request includes:
* `eventId` and `processEventId`: Useful for tracing the order event in Limio
* The original order payload (`event`)
* `pluginErrorOutput`: A list of plugin errors that occurred
Example Error Reporting webhook
```json
{
eventId: 'event-f3a77aa153fdab191479b484d85375e6',
processEventId: 'process_event-f3a77aa153fdab191479b484d85375e6',
event: {
message: 'Order Received',
type: 'order.refund',
event: {
recipientDetails: [Object],
billingDetails: [Object],
hasDelivery: false,
__spec_version: '2',
external_id: '801377f3-e59d-4d2a-a737-f85d24a207b7',
orderItems: [Array],
tracking: [Object],
orderState: 'submitted',
mode: 'test',
total: [Object],
chooseDate: false,
isRedeem: false,
deliveryDetails: [Object],
isGift: false,
payment: [Object],
customerDetails: [Object],
order_type: 'refund',
orderDate: '2023-01-01T00:00:00.000Z'
}
},
pluginErrorOutput: [ { name: 'zuora', message: 'Invalid service id: [undefined]' } ]
}
```
---
# 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/overview.md?ask=&goal=
```
`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.