easyPoints

# 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 Integer 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 Integer 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"
}

# point_balances/export

This webhook will trigger whenever an api csv export request is made from the point balances route.

# Payload

Field Type Description
url String the url where the file is being hosted. Note: these urls are only accessible for 1 hour

Example:

{
  "url": "https://loyalty.slrs.io/FILENAME_URL_HERE
}

# 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

The following fields will 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
topic String The easyPoints event that the webhook is subscribed to
uid String Unique identifier for the webhook subscription

Example:

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

{
    "status": 200,
    "data": {
      "activated_at": "2023-01-01T00:00:00Z",
      "active": true,
      "callback_url": "https://your_callback_url.com",
      "topic": "point_allotment/cascade",
      "uid": "03d78626-70c2-11ee-a398-0a6257f44932"
    }
}

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
}

← Pagination →