> 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/integrations/order-orchestration/webhooks-and-notifications.md). # Webhooks and Notifications Limio provides several mechanisms to notify external systems about order events. These range from asynchronous webhooks, to Salesforce Platform Events for CRM automation, to error webhooks for monitoring. ## Asynchronous Webhooks Async webhooks are **separate from the plugin pipeline**. They are non-blocking — they cannot affect the order outcome — and are used for notifications, data synchronisation, and analytics. {% hint style="warning" %} Async webhooks (e.g., Order Submitted) fire as soon as the Limio order is created, **regardless of whether all plugins in the orchestration pipeline succeed or fail**. For example, if Zuora billing fails after Salesforce has already processed, the Order Submitted webhook will still have been sent. Use the [Error webhook](#error-webhook) to detect failures and trigger compensation logic. {% endhint %} ### Available Webhook Types | Webhook | Trigger | | ------------------------------- | -------------------------------------------------- | | **Order Submitted** | After a new order is submitted via Limio Shop | | **Subscription Created** | After a subscription is created | | **Address Change** | After a delivery or billing address is updated | | **Payment Method Change** | After a payment method is updated | | **Subscription Offer Change** | After a subscription offer is switched | | **Subscription Offer Addition** | After a new offer is added (e.g., cancel/save) | | **Subscription Cancellation** | After a subscription is cancelled | | **Update Customer Details** | After customer details are updated | | **Update Subscription** | After a subscription is modified (e.g., add-ons) | | **Entitlements Updated** | After entitlements reach Active status (new order) | | **Checkout Initiated** | After a customer initiates the checkout | | **Cancel Attempted** | After a customer attempts to cancel | | **Payment Method Added** | After a payment method is added | | **Address Added** | After an address is added | ### How to Configure 1. Go to **Settings > General Settings > Webhooks** 2. Enter the destination URL for each webhook type you want to enable Limio will send a POST request to the configured URL with the relevant object payload. See the [Webhooks Overview](https://docs.limio.com/developers/webhooks/overview) in the developer docs for payload schemas. ## Salesforce Platform Events If you use the **Salesforce V3** plugin, Limio can publish **Platform Events** (`i42as__OrderEvent__e`) to your Salesforce org. These events allow you to build automation using Salesforce Lightning Flows — no code required for basic data mapping. ### Supported Event Types These are the values Limio publishes in the event's `Type` field (`i42as__Type__c`). Several Limio order types share a single event type, so branch on `i42as__OrderType__c` when you need to tell them apart. | Event Type | Description | Limio order types | | -------------------------- | ------------------------------------------------------- | ------------------------------------------------ | | `NEW_ORDER` | New subscription purchase, including gift purchases | `new`, `submitted` | | `CHANGE_OFFER` | Offer switch/upgrade/downgrade | `change_offer` | | `CANCEL_REQUEST` | Subscription cancellation, or an intent to cancel | `cancel_subscription`, `cancel_intent` | | `ADD_OFFER` | Additional offer added | `add_offer`, `credit` | | `CHANGE_PAYMENT_REQUEST` | Payment method change | `change_payment` | | `COMPENSATION_PAYMENT` | Refund processed | `refund` | | `REQUEST_RENEWAL` | Subscription renewal | `renew` | | `CHANGED_DELIVERY_ADDRESS` | Delivery address update | `change_address` | | `UPDATE_SUBSCRIPTION` | Subscription modification, or a customer details update | `update_subscription`, `update_customer_details` | | `DATA_CAPTURE` | Data capture form submission | `data_capture` | {% hint style="info" %} A gift purchase is published as `NEW_ORDER` (with the gift-specific fields added), and a refund is published as `COMPENSATION_PAYMENT`. There is no `NEW_GIFT_ORDER`, `REFUND` or `UPDATE_CUSTOMER` event type. {% endhint %} ### How Platform Events Work 1. The Salesforce V3 plugin fires a Platform Event to your Salesforce org as part of order processing. 2. A **Platform Event-Triggered Flow** in Salesforce listens for the event. 3. The Flow maps event fields to Salesforce objects (e.g., Account, Opportunity, Asset). 4. Salesforce records are created or updated based on the mapping. If you use the **Limio for Salesforce** managed package, a pre-built Flow (`Listen to Limio OrderEvent__e`) is included. Otherwise, you can create a Flow from scratch. ### Configuring Which Events Are Sent You can choose to send events for all order types or only specific ones (e.g., just new orders and cancellations). The `orderTypes` option on the Salesforce V3 plugin controls this. ### Sending the Full Order Payload By enabling the `sendWholeOrder` option, the `i42as__LimioOrder__c` field is populated with a JSON string containing the Limio order object. This provides access to customer details, custom fields, billing data, and tracking information within your Salesforce Flows. Most event types send a reduced version of the order rather than the whole thing. See [Platform Events Field Definitions](/integrations/populating-salesforce-data/platform-events-flexible/platform-events-definitions.md) for which types send the reduced order and which send it in full. Additional fields can be included using the `orderDataOptions` configuration. Contact to configure this. ### Learn More * [Setup Platform Events and Flows](/integrations/populating-salesforce-data/platform-events-flexible/setup-platform-events.md) * [Platform Events Field Definitions](/integrations/populating-salesforce-data/platform-events-flexible/platform-events-definitions.md) * [Listen to OrderEvent Flow](/integrations/populating-salesforce-data/platform-events-flexible/orderevent-flow.md) * [Salesforce V3 Platform Event Errors](/integrations/using-limio-for-salesforce/troubleshooting/v3-platform-event-errors.md) ## Error Webhook The **Error webhook** fires when any plugin fails during order processing. It provides visibility into failures across the entire orchestration pipeline and can be used for alerting, logging, or triggering recovery workflows. ### When Does It Fire? Any time a plugin in the orchestration pipeline fails — whether it's a billing failure in Zuora, a Salesforce error, a callout timeout, or any other plugin error. The most common use case is catching **payment failures**. ### How to Configure 1. Go to **Settings > General Settings > Webhooks** 2. Under **Error Reporting**, enter the destination URL ### Payload Each POST request includes: | Field | Description | | ------------------- | ----------------------------------------------- | | `eventId` | The Limio event ID for tracing | | `processEventId` | The process event ID for detailed investigation | | `event` | The original order payload | | `pluginErrorOutput` | Array of plugin errors with name and message | Example: ```json { "eventId": "event-f3a77aa153fdab191479b484d85375e6", "processEventId": "process_event-f3a77aa153fdab191479b484d85375e6", "event": { "message": "Order Received", "type": "order.new", "event": { "..." } }, "pluginErrorOutput": [ { "name": "zuora", "message": "Payment declined: Insufficient funds" } ] } ``` ## Custom Post-Processing Webhooks For advanced requirements, Limio supports custom webhook plugins that run in the **post-processing** phase — after all standard plugins have completed. These webhooks have access to enriched order data, including CRM IDs and gift codes created during processing. Custom post-processing webhooks are useful for fulfilment notifications that require data generated during order processing (e.g., a Salesforce Account ID or Zuora subscription number). Contact to discuss custom webhook requirements. --- # 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/integrations/order-orchestration/webhooks-and-notifications.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.