Ctrlk
Support Request
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Example Customer webhook payload
{
  "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

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

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

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
Example Entitlement webhook payload on suspend or cancellation

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 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 to retrieve email and user details once the customer authenticates.

Example Checkout Initiated webhook

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. 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
PreviousOAuth Bearer Token
NextUsing Webhooks

Last updated

Was this helpful?