Webhooks Overview

Here’s a list of all webhooks available in Limio, with a short description of what each one does.

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.

The Customer object sent in the webhook is described in the following schema:

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.

The Subscription object sent in the webhook is described in the following schema:

Order

The Order object will be sent when the user goes through the action described below (address change, payment method change, subscription offer change...). The Order object sent will look as below:

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.

Entitlement

Entitlements Updated

The entitlement webhook notifies external systems when entitlements have been updated. It is triggered only when a subscription reaches an Active status, such as after a successful new order. Read more about how entitlements work in Limio

For a cancellation, we recommend using the Order webhook for Subscription Cancellation to update entitlements.

The Entitlement Object sent via webhook will look as below:

Events

Checkout Initiated

This webhook is used to receive the Event object after the Checkout is initiated by the customer using the Limio Shop.

Example Checkout Initiated webhook

{
  "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.

When is this Error webhook fired?

When a customer places an order in Limio, it is handled by the 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

{
 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]' } ]
}