Using Webhooks

Use webhooks to be notified of changes in the Limio application.

You can use webhooks within the Limio application to be notified anytime a specific event occurs. Limio can be configured to generate a webhook whenever any significant event occurs, which can then be handled by a designated endpoint in your application. You just need to specify the URL that needs to receive the data within the settings of the Limio application. Every time that event occurs in Limio, Limio makes a call to that endpoint sending the JSON object involved in the action.

Here is an example of the URL you have to set in the Webhooks fields: https://your-domain.com/your-endpoint

Why webhooks?

Webhooks are intended to be used for background tasks and asynchronous changes. A key use case is to notify a third-party application such as a billing or entitlement that a new order has been created or a subscription has been changed, and needs to be added to the third-party systems.

Authenticating Webhooks

Should the webhook need to be authenticated this can be done by adding a Basic Auth authentication provider in the Limio App. Select Basic Auth and enter the Name, Username and Password fields, where name is the base url of the endpoint that the webhook is being sent to.

How do I configure a webhook in Limio?

In order to receive a webhook you need to configure an endpoint for the appropriate endpoint type. You can find the webhook configuration in Settings > General Settings > Webhooks.

Webhook event format

The body of the webhook request will be the edited item that triggered the webhook.

Viewing a webhook

Webhooks can be viewed by logging into the app and navigating to Subscriptions > Webhooks. Alternatively, you can navigate directly to https://[your-limio-domain]/objects/webhooks/limio

List of events that will trigger a webhook

Below you will find all the Webhooks that Limio offers you to configure and a brief description of each one.

Customer

Customer Created / Updated

This webhook is used to receive the Customer object after a Customer gets created or updated when a new Subscription is created through the Limio Shop or the Limio Checkout for Salesforce.

Example:

{
  "data": {
    "name": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "purchaseCountry": "string",
    "trialist": boolean
  },
  "status": "string",
  "record_type": "string",
  "owner": "string",
  "id": "string",
  "service": "string",
  "created": "datetime",
  "updated": "datetime",
  "reference": "string",
  "mode": "string",
  "identities": [
    {
      "sub": "string",
      "iss": "string",
      "https://limio.com/service": "string",
      "https://limio.com/type": "string"
    },
    {
      "sub": "string",
      "iss": "string",
      "https://limio.com/service": "string",
      "https://limio.com/type": "string"
    }
  ]
}

Subscription

Subscription Created

This webhook is used to receive the Subscription object after a Subscription gets created using the Limio Shop, Manage My Account functionalities, or the Limio Checkout for Salesforce.

Example

{
  "name": "string",
  "tracking": {
    "offers": [
      "string"
    ],
    "campaign": "string",
    "tag": "string"
  },
  "offer": {
    "name": "string",
    "path": "string",
    "parent_path": "string",
    "id": "string",
    "data": {
      "created": "datetime",
      "description": "string",
      "team": "string",
      "validFrom": "datetime",
      "duplicatedFrom": "string",
      "type": "string",
      "record_type": "string",
      "tags": [
        "string"
      ],
      "segments": [
        "string"
      ],
      "products": [
        "string"
      ],
      "baseTemplate": "string",
      "childSorting": {
        "offer-path": "number"
      },
      "familyName": "string",
      "name": "string",
      "modified": "datetime",
      "attributes": {
        "offer's attributes"
      },
      "headline": "string",
      "user": "string",
      "status": "string",
      "validTo": "datetime",
      "subline": "string"
    },
    "type": "item"
  },
  "quantity": "number",
  "termEndDate": "datetime",
  "price": {
    "summary": {
      "headline": "string"
    },
    "currency": "string",
    "amount": "number"
  },
  "selectedProducts": {},
  "details": null,
  "id": "string",
  "purchaseCountry": "string",
  "startDate": "datetime",
  "products": []
}

Order

The Order object has seven Webhooks that get activated for different reasons.

Address Change

This webhook is used to receive the Order object after the Address gets updated using the Limio Shop or Manage My Account functionalities.

Payment Method Change

This webhook is used to receive the Order object after the Payment Method gets updated using the Limio Shop, or Manage My Account functionalities, or the Limio Checkout for Salesforce.

Subscription Offer Change

This webhook is used to receive the Order object after the Subscription Offer gets updated using the Limio Shop or Manage My Account functionalities.

Subscription Offer Addition

This webhook is used to receive the Order object after a new Subscription Offer is added using the Limio Shop or Manage My Account functionalities.

Subscription Cancellation

This webhook is used to receive the Order object after the Subscription is cancelled using the Limio Shop or Manage My Account functionalities.

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 the Limio Shop.

Example:

{
  "tracking": {
    "lmo_offer": "string",
    "offers": ["string"],
    "campaign": "string",
    "tag": "string"
  },
  "country": "string",
  "redirectUrl": null,
  "billingDetails": {
    "country": "string",
    "address2": "string",
    "city": "string",
    "address1": "string",
    "postalCode": "string",
    "company": "string",
    "state": "string"
  },
  "recaptchaPayload": null,
  "studentDetails": {
    "course": "string",
    "university": "string",
    "graduationYear": "string"
  },
  "student": boolean,
  "hasDelivery": boolean,
  "__spec_version": "string",
  "external_id": "string",
  "source": "string",
  "isTrial": boolean,
  "orderItems": [
    {
      "name": "string",
      "offer": {
        "name": "string",
        "path": "string",
        "id": "string",
        "type": "string",
        "data": {
          "price__limio": [],
          "attachments": [
            {
              "name": "string",
              "path": "string",
              "type": "string",
              "url": "string"
            }
          ],
          "created": "string",
          "duplicatedFrom": "string",
          "type": "string",
          "version": "string",
          "record_type": "string",
          "products": [
            {
              "baseTemplate": "string",
              "entitlements": [{ "$ref": "string" }],
              "path": "string",
              "created": "datetime",
              "modified": "datetime",
              "attributes": {
                "entitlements": ["string"],
                "description__limio": "string",
                "related_products__limio": [
                  "string"
                ],
                "display_name__limio": "string",
                "has_delivery__limio": boolean,
                "product_code__limio": "string"
              },
              "record_subtype": null,
              "record_type": "string"
            }
          ],
          "productBundles": [
            {
              "revenue_split": "string",
              "product_path": "string",
              "rate_plan": "string"
            }
          ],
          "baseTemplate": "string",
          "path": "string",
          "priceReference": "string",
          "price": [],
          "name": "string",
          "modified": "datetime",
          "attributes": {
            "checkout_description__limio": "string",
            "price__limio": [
              {
                "delay_interval_type": "string",
                "subscription_start_day": "",
                "delay_interval": null,
                "label": "string",
                "trigger": "string",
                "repeat_count": number,
                "type": "string",
                "name": "string",
                "repeat_interval": number,
                "attributes": [],
                "repeat_interval_type": "string",
                "value": "string",
                "currencyCode": "string"
              }
            ],
            "default_quantity_options__limio": {},
            "allowed_countries__limio": [
              "string"
            ],
            "label__limio": [
              "string",
            ],
            "contentGroup": "string",
            "term__limio": { "length": number, "type": "string" },
            "display_price__limio": "string",
            "ltm_gaBundleID": "string",
            "cta_text__limio": "string",
            "mma_description__limio": "string",
            "payment_types__limio": ["string"],
            "sales_channel__limio": ["string"],
            "offer_features__limio": "string",
            "rate_plan__zuora": "string",
            "display_name__limio": "string",
            "group__limio": "string",
            "best_value__limio": boolean,
            "checkout__limio": {
              "checkout_type": "string",
              "external_url": "string"
            },
            "push_to_checkout__limio": boolean,
            "autoRenew__limio": boolean,
            "offer_type__limio": "string"
          },
          "id": "string",
          "user": "string"
        },
        "version": "string"
      },
      "details": "string",
      "id": "string",
      "price": {
        "summary": { "headline": "string" },
        "currency": "string",
        "amount": number
      },
      "products": [
        {
          "baseTemplate": "string",
          "entitlements": [{ "$ref": "string" }],
          "path": "string",
          "created": "datetime",
          "modified": "datetime",
          "attributes": {
            "entitlements": ["string"],
            "description__limio": "string",
            "related_products__limio": [
              "string"
            ],
            "display_name__limio": "string",
            "has_delivery__limio": boolean,
            "product_code__limio": "string"
          },
          "record_subtype": null,
          "record_type": "string"
        }
      ]
    }
  ],
  "orderState": "string",
  "paymentType": "string",
  "mode": "string",
  "total": { "amount": number, "currency": "string" },
  "isRedeem": boolean,
  "deliveryDetails": {
    "country": "string",
    "address2": "string",
    "city": "string",
    "address1": "string",
    "postalCode": "string",
    "company": "string",
    "state": "string"
  },
  "variant": "string",
  "isGift": boolean,
  "autoRenew": boolean,
  "payment": {
    "type": "string",
    "zuora": {
      "AuthorizeResult": "string",
      "zThreeDs2TxId": "string",
      "signature": "string",
      "ThreeDSResult": "null",
      "responseFrom": "string",
      "token": "string",
      "threeDs2token": "string",
      "success": boolean,
      "threeDs2Ts": "string",
      "tenantId": "string",
      "nextStep": "string",
      "refId": "string",
      "threeDs2Sig": "string",
      "paymentGateway": "string"
    }
  },
  "customerDetails": {
    "firstName": "string",
    "lastName": "string",
    "marketingPrefs": {},
    "email": "string"
  },
  "order_type": "string",
  "recipientDetails": { "startNow": boolean, "sendEmail": boolean },
  "redirectState": null,
  "subRef": null,
  "requestCompany": boolean,
  "allowedCountries": [
    "string"
  ],
  "userDetails": {
    "sub": "string",
    "firstName": "string",
    "lastName": "string",
    "string": {
      "iss": "string",
      "sub": "string"
    },
    "userSubscriptionType": "string",
    "exp": number,
    "given_name": "string",
    "iat": number,
    "family_name": "string",
    "issuer": "string",
    "email": "string"
  },
  "subId": null,
  "subscriptionReference": null,
  "chooseDate": boolean,
  "checkoutId": "string",
  "subscriptionId": null,
  "orderDate": "datetime",
  "owner": "string",
  "name": "string",
  "identities": [
    {
      "sub": "string",
      "iss": "string",
      "https://limio.com/service": "string",
      "https://limio.com/type": "string"
    },
    {
      "sub": "string",
      "iss": "string",
      "https://limio.com/service": "string",
      "https://limio.com/type": "string"
    }
  ]
}

Entitlement

Entitlements Updated

Notifies a system that entitlements have been updated. The entitlement webhook only sends when the subscription has a status of active, i.e. the order has been processed successfully. This webhook is fired in the case of a new order and a switch.

Example:

{
    "tracking": {
        "subscription": "27U35085IL80"
    },
    "updated":"2023-03-07T12:59:07.266Z",
    "owner":"id-1ccfed61a10e54601bded1a85877fdc5",
    "entitlements": [{"code":"SKU0010001"}],
    "identities":[
        {
            "sub":"77de4afa-6676-468f-944f-3a8561c888a8",
            "iss":"https://admin.dev.some-account.authprovider.io",
            "https://limio.com/service":"zephr",
            "https://limio.com/type":"user_id"
        },
        {
            "sub":"0018E00001zzlpgQAA",
            "iss":"salesforce",
            "https://limio.com/service":"salesforce",
            "https://limio.com/type":"account"
        }
    ]
}

In the case of a switch, Limio will also pass the effective date of that change:

"effectiveDate":"2024-03-11"

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

Events

Checkout Initiated

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

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.

Example:

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

Error Reporting

Error

This webhook is used to receive the Error object generated when an error occurs during order processing.

Example

{
 eventId: "string",
 processEventId: "string",
 event: {
  message: "string",
  type: "string",
  event: {
   recipientDetails: Object,
   billingDetails: Object,
   hasDelivery: boolean,
   __spec_version: "string",
   external_id: "string",
   orderItems: Array,
   tracking: Object,
   orderState: "string",
   mode: "string",
   total: Object,
   chooseDate: boolean,
   isRedeem: boolean,
   deliveryDetails: Object,
   isGift: boolean,
   payment: Object,
   customerDetails: Object,
   order_type: "string",
   orderDate: datetime
  }
 },
 pluginErrorOutput: [ 
  { 
   name: 'zuora' | 'salesforce' | 'salesforceRefs'..., 
   message: "string" 
  } 
 ]
}

Last updated