# Webhooks

Subscribe to webhooks to receive event notifications within easyPoints via the easyPoints API. This documentation outlines the available topics, webhook response requirements, retry policy, webhook verification and the Webhook API endpoints.

# Responding to Webhooks

To acknowledge successful receipt of a webhook, ensure that your response returns a status code of 200 within 5 seconds. Otherwise, the system will retry sending the webhook.

# Webhooks Retry Policy

Webhooks will be resent if they are not successfully sent or acknowledged. Webhooks will be retried up to 20 times using an exponential backoff algorithm with a small amount of jitter. The last attempt can be expected 12 days after the initial attempt.

# Webhook Verification

The webhook API uses Bearer Token Authentication. The token is generated with your API Secret Key encrypted with HS256 hashing algorithm. To generate a Secret Key, please refer to the Api Access section.

Below is an example of verifying a webhook using Node.js:

const jwt = require('jsonwebtoken');
const token = req.headers.authorization.split(' ')[1];

try {
  const decoded = jwt.verify(token, secretKey);
  // ...
} catch (error) {
  // Handle invalid or expired tokens
}

# Available Topics

Currently, two webhooks topics can be subscribed to:

point_allotment/cascade
point_balance/update

# point_allotment/cascade

This webhook will trigger when points are allocated to a point balance.

# Payload

Field	Type	Description
`allotted_at`	Datetime	The date and time when the points were allotted (in ISO8601 format).
`customer`	Object	Information about the associated customer.
`customer.shopify_id`	Number	The Shopify ID of the customer.
`point_value`	Number	The value of the points allotted.
`type`	String	The point type (e.g "fulfillment").
`uid`	String	Unique identifier for the point allotment event.

Example:

{
  "allotted_at": "2023-01-02T12:00:00.000000",
  "customer": {
    "shopify_id": 7370359931169
  },
  "point_value": 1,
  "type": "fulfillment",
  "uid": "96304480-7203-11ee-b8cd-0a6257f44932"
}

# point_balance/update

This webhook will trigger whenever a point balance is updated.

This event will trigger if:

A point balance becomes active
A point balance earns or spends points
A point balance's expiration is updated
The name or birthday of the customer changes
The customer opted in for store marketing

Note that updating expiration settings will change point balances' expiration field but will not trigger the update point balance webhook.

# Payload

Field	Type	Description
`accepts_marketing`	Boolean	Indicates if the customer accepts shopify marketing.
`account_enabled`	Boolean	Indicates if the customer's account is enabled.
`balance`	Number	The current point balance of customer.
`birthday`	Date	The customer's birthday (in ISO8601 format).
`customer`	Object	Information about the associated customer.
`customer.shopify_id`	Number	The Shopify ID of the customer.
`name`	String	The name of the customer.
`point_expiration_date`	Datetime	The date and time when the points will expire (in ISO8601 format).
`uid`	String	Unique identifier for the point balance.

Example:

{
  "accepts_marketing": false,
  "account_enabled": true,
  "balance": 100,
  "birthday": "2000-01-01",
  "customer": {
    "shopify_id": 123456789
  },
  "name": "John Doe",
  "point_expiration_date": "2023-01-01T23:59:59+09:00",
  "uid": "f85478b0-70ba-11ee-95f2-0a6257f44932"
}

# Webhook API

API endpoints to get, create, and delete webhooks subscriptions.

# Base Route

/api/shopify/webhooks

# Fetching Webhook Subscriptions

# Route

Use the following GET route to retrieve all webhooks for your shop:

GET /api/shopify/webhooks

# Result

The following fields may be returned:

Key	Type	Definition
`activated_at`	Datetime	The date and time when the webhook subscription became active (ISO8601 format)
`active`	Boolean	Indicates if the webhook subscription is active
`callback_url`	String	The URL to which the webhook is sent
`shop_uid`	String	Unique identifier for your shop
`topic`	String	The easyPoints event that the webhook is subscribed to
`uid`	String	Unique identifier for the webhook subscription

Example:

GET "https://loyalty.slrs.io/api/shopify/webhooks"

{
    "data": [
        {
            "activated_at": "2023-01-01T00:00:00Z",
            "active": true,
            "callback_url": "https://your_callback_url.com/1",
            "shop_uid": "e378ad94-70ba-11ee-9c58-0a6257f44932",
            "topic": "point_allotment/cascade",
            "uid": "c2fb2e64-70c1-11ee-a2eb-0a6257f44932"
        },
        {
            "activated_at": "2023-01-01T00:00:00Z",
            "active": true,
            "callback_url": "https://your_callback_url.com/2",
            "shop_uid": "e378ad94-70ba-11ee-9c58-0a6257f44932",
            "topic": "point_balance/update",
            "uid": "03d78626-70c2-11ee-a398-0a6257f44932"
        }
    ]
}

# Creating a Webhook Subscription

# Route

Use the following POST route to create a webhook:

POST /api/shopify/webhooks

# Fields to Submit

The following fields must be submitted to create a webhook subscription:

Key	Type	Required	Definition
`topic`	String	✔️	An available webhook topic
`callback_url`	String	✔️	The URL where the webhook should be sent

Refer to the Available Topics section above for a list of available webhook topics.

# Result

Example:

POST "https://loyalty.slrs.io/api/shopify/webhooks"
{
  "topic": "point_allotment/cascade",
  "callback_url": "https://your_callback_url.com"
}

{
    "status": 200
}

WARNING

Creating a webhook subscription for a topic that is already subscribed to won't update or replace the existing subscription. To replace an existing webhook subscription, you should first delete the original webhook subscription for that topic.

# Deleting a Webhook Subscription

# Route

Use the following DELETE route to delete a webhook:

DELETE /api/shopify/webhooks

# Fields to Submit

The following fields must be submitted to delete a webhook subscription:

Key	Type	Required	Definition
`topic`	String	✔️	An available webhook topic

Refer to the Available Topics section above for a list of available webhook topics.

# Result

Example:

DELETE "https://loyalty.slrs.io/api/shopify/webhooks"
{
  "topic": "point_allotment/cascade"
}

{
    "status": 200
}

← Async API Frequently Asked Questions →