Webhooks

In this section, you will learn about webhook integrations and notifications in Open Loyalty.

Webhooks Overview

Webhooks is a mechanism allowing us to send HTTP requests to the URL configured by Admin, triggered by an Event, such as customer registration, transaction creation, customer data edit, etc. The new webhook mechanism is based on subscriptions to individual events occurring in the system. The following webhooks are accessible using the subscription method:

• TransactionRegistered

• PointsWillExpire

• LevelWillExpire

• AvailablePointsAmountChanged

• TransactionAssignedToCustomer

• RewardRedemptionStatusChanged

• CampaignEffectWasApplied

• CustomerWasRegisteredWithoutActivation

• CustomerUpdated

• CustomerRequestedSendActivationCode

• CustomerRequestedPasswordReset

• CustomerRegistered

• CustomerPhoneNumberWasChanged

• CustomerLevelChanged

• CustomerEmailWasChanged

• CustomerDeactivated

• CustomerBoughtReward

• CouponWillExpire

To enable gradual migration to the new mechanism, we have prepared a legacy mode, thanks to which the data sent in webhooks are in the same format as in the earlier version of the system.

How to configure the webhooks?

The subscription method means that you can decide which webhooks are active - you do not receive data from the ones you are not interested in.

You can subscribe to the webhook in two ways.

One way is to use the admin panel, which will allow you to configure webhooks using a graphical interface, and the second is to use the endpoint.

To get to Webhooks in the admin panel head to Webhooks

• Webhook name - Webhook name in the system

• Active from - Date of webhook activation

• Legacy - Information is webhook is working in the Legacy mode

• URL - Address to which the webhook is sent

To make it easier to search for a specific webhook, you can use filtering based on the headers or use a search table in the upper right corner:

Adding a new webhook subscription

To add a new webhook subscription:

1. log in to the app as an Administrator

2. Go to Webhooks

3. Click the ADD NEW WEBHOOK button

4. Fill in the required fields

5. Click ADD WEBHOOK

From the dropdown list choose the webhook you'd like to subscribe to. Enter the address to which the webhooks will be sent. In addition, you can add multiple headers to the webhook however, it is not required by the system.

After saving, when the correct event is executed, the webhook will be sent to the previously entered address.

You can also subscribe to the webhook by using the endpoint:

/api/{storeCode}/webhook/subscription

Get all webhook subscriptions.

If sorting is not chosen, the rows will be returned in an unspecified order.
To sort a result, use an _orderBy parameter in query.

GEThttp://openloyalty.localhost/api/{storeCode}/webhook/subscription

Path parameters

storeCode*string

Store code

Query parameters

Response

200401403

List of webhook subscriptions

Body

application/json

itemsarray of WebhookSubscription (object)

totalSearchableTotalResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('http://openloyalty.localhost/api/{storeCode}/webhook/subscription', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401403

{
  "items": [
    {
      "webhookSubscriptionId": "text",
      "eventName": "text",
      "url": "text",
      "legacy": false,
      "createdAt": "2024-12-16T15:37:13.110Z"
    }
  ],
  "total": {
    "all": 0,
    "filtered": 0
  }
}

Create a new webhook subscription

POSThttp://openloyalty.localhost/api/{storeCode}/webhook/subscription

Path parameters

storeCode*string

Store code

Body

application/json

webhookSubscriptionCreateWebhookSubscriptionFormType (object)

Response

200400401403

Return created webhook subscription ID.

Body

application/json

webhookSubscriptionIdstring (uuid)

Example: "00000000-0000-0000-0000-000000000000"

Request

JavaScriptCurlPython

const response = await fetch('http://openloyalty.localhost/api/{storeCode}/webhook/subscription', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400401403

{
  "webhookSubscriptionId": "00000000-0000-0000-0000-000000000000"
}

In the body request, put the name of the webhook in eventName and the address of the service you want the data to be sent to in the URL

Webhook body example

Webhook 'account.available_points_amount_changed' automatically informs whenever the number of available points in a user's account changes. The update information is presented in the form of a body containing the following information.

{
"eventName": "string",
"storeCode": "string",
"createdAt": "2019-08-24T14:15:22Z",
"data": {
"customer": {},
"accountId": "string",
"amount": null,
"amountChange": null,
"amountChangeType": "string",
"wallet": {}
}

Webhook can be used as a trigger to execute an action on the user side of the application.

Webhooks trigger actions

In this section, you can review the actions that trigger specific webhooks. This will help you choose the best options for your marketing automation.

Webhook Name	Trigger Actions
TransactionRegistered	Transaction registered when creating transactions: in the UI via API:https://apidocs.openloyalty.io/#tag/Transactions/operation/_transactionPos Transaction import
PointsWillExpire	Webhook is triggered X days before the units expire depending on the setup in the Expiring Notifications -> Expiring units notifications.
LevelWillExpire	Webhook is triggered X days before the tier recalculation depending on the setup in the Expiring Notifications -> Tier recalculation notification
AvailablePointsAmountChanged	When units are spent (reward purchase with points, or by using the https://apidocs.openloyalty.io/#tag/Points/operation/pointsPostTransferSpend endpoint) When units are added or deducted manually by an admin When a campaign adds or deducts units Importing unit transfers When the unit transfer is cancelled ( https://apidocs.openloyalty.io/#tag/Points/operation/pointsPostTransferCancel ) When pending units get activated (either automatically, or manually by the admin) When units expire (either automatically, or manually by the admin) When units are blocked ( https://apidocs.openloyalty.io/#tag/Points/operation/pointsPostTransferBlock ) When units are unblocked ( /api/:storeCode/points/:transfer/cancel ) When units are transferred between members (2 webhooks are sent - one for the receiver, and one for the sender)
TransactionAssignedToCustomer	Matching transactions manually in the UI Matching transaction via API: https://apidocs.openloyalty.io/#tag/Transactions/operation/transactionPostMemberAssi Importing matches
RewardRedemptionStatusChanged	Changing the status of the reward in the UI or via API: https://apidocs.openloyalty.io/#tag/Reward/operation/redemptionPostStatu
CampaignEffectWasApplied	The member receives points/ rewards or member custom attributes from the campaign. Example flow here.
CustomerWasRegisteredWithoutActivation	Member created without activation using the endpoint: POST/api/{storeCode}/member/register
CustomerUpdated	Adding/updating member basic information: first and last name phone number email loyalty card number gender registration date birthday date tier Adding member custom attributes when editing a member in the Admin UI or API: PUT/api/{storeCode}/member/{member} Adding/updating address/company details Updating Agreements The above actions can be taken in the Admin Panel or via API.
CustomerRequestedSendActivationCode	Member requests an activation code using the endpoint: POST/api/{storeCode}/member/{member}/send-code Member requests resending the activation code using the endpoint: POST/api/{storeCode}/member/resend-code
CustomerRequestedPasswordReset	An active member who has been created within the endpoint: POST/api/{storeCode}/member/register requests a password reset using POST/api/{storeCode}/member/password/reset/reque
CustomerRegistered	Member created in the Admin panel Member created via API: POST/api/{storeCode}/member
CustomerPhoneNumberWasChanged	Logged member updates phone number on their profile.
CustomerLevelChanged	Manually changing a tier on a member profile (lower and higher) While reaching the threshold of tier from conditions of the tier set While creating a new member when the lowest tier is automatically assigned The above actions can be taken in the Admin Panel or via API.
CustomerEmailWasChanged	Logged member updates an email on their profile.
CustomerDeactivated	Member Deactivated in the Admin Panel Member deactivated via the API: POST/api/{storeCode}/member/{member}/deactivat
CustomerBoughtReward	Manually assigning rewards to a member The reward received from the Camaign Effect The reward bought from the Reward Catalog The above actions can be taken in the Admin Panel or via API.
CouponWillExpire	Webhook is triggered X days before the reward coupon expires depending on the setup in the Expiring Notifications -> Expiring coupons notifications.

Expiring Notifications

Available in Webhooks -> EXPIRING NOTIFICATIONS in the upper right corner.

Set when the system will send messages to Members regarding their Units, coupons, and Tier recalculating.

• Days before expiring Units to notify the user

• Days before expiring coupons to notify the user

• Days before Tier recalculation to notify the user

Just set the number of days that suit you and click the 'Save Settings' button.