# 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

| Event Type                 | Description                    |
| -------------------------- | ------------------------------ |
| `NEW_ORDER`                | New subscription purchase      |
| `CHANGE_OFFER`             | Offer switch/upgrade/downgrade |
| `CANCEL_REQUEST`           | Subscription cancellation      |
| `ADD_OFFER`                | Additional offer added         |
| `CHANGE_PAYMENT_REQUEST`   | Payment method change          |
| `NEW_GIFT_ORDER`           | Gift subscription purchase     |
| `REFUND`                   | Refund processed               |
| `REQUEST_RENEWAL`          | Subscription renewal           |
| `CHANGED_DELIVERY_ADDRESS` | Delivery address update        |
| `UPDATE_CUSTOMER`          | Customer details update        |
| `UPDATE_SUBSCRIPTION`      | Subscription modification      |
| `DATA_CAPTURE`             | Data capture form submission   |

### 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` field is populated with a JSON string containing the full Limio order object. This provides access to customer details, custom fields, billing data, and tracking information within your Salesforce Flows.

Additional fields can be included using the `orderDataOptions` configuration. Contact <support@limio.com> to configure this.

### Learn More

* [Setup Platform Events and Flows](https://docs.limio.com/integrations/populating-salesforce-data/platform-events-flexible/setup-platform-events)
* [Platform Events Field Definitions](https://docs.limio.com/integrations/populating-salesforce-data/platform-events-flexible/platform-events-definitions)
* [Listen to OrderEvent Flow](https://docs.limio.com/integrations/populating-salesforce-data/platform-events-flexible/orderevent-flow)
* [Salesforce V3 Platform Event Errors](https://docs.limio.com/integrations/using-limio-for-salesforce/troubleshooting/v3-platform-event-errors)

## 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 <support@limio.com> to discuss custom webhook requirements.