Webhooks

You can use webhooks to receive notifications about events that happen in LoyaltyLion, such as a customer earning points or moving into a new tier. This is more efficient than polling our API periodically.

Receiving webhooks

Once you have registered a webhook subscription, LoyaltyLion will issue a HTTP POST request to the specified URL every time that event occurs. The request body will be a JSON object containing the webhook metadata and payload.

interface WebhookEventRequestBody {
  // a globally unique ID for this webhook event
  id: string
  // event that triggered this webhook
  topic: string
  // an ISO 8601 string representing the date this webhook was sent
  created_at: string
  // a resource-specific payload
  payload: object
}

The webhook event payload will depend on the topic which triggered the webhook. See webhook topics for details of our available topics and their respective payloads.

In addition to the request body, the request will include the following headers you can use to handle the event.

HeaderDescription
x-loyaltylion-site-domainThe domain of the associated site, e.g. shop.example.com
x-loyaltylion-topice.g. customers/update

Responding to webhooks

Your webhook must acknowledge it received the event by responding with a 200 OK response. Any response outside of the 200 range will be treated as an error, including 3xx redirects which will not be followed.

Failed webhooks will be retried with an exponential backoff until a success response is received or the webhook subscription is removed.

Managing webhook subscriptions

You can manage webhook subscriptions through our webhook API.

Webhook subscriptions are scoped to the OAuth app (client id) which created them, i.e. an OAuth client can only view their own webhook subscriptions. Webhooks created using token & secret auth are never visible to OAuth clients.

Available actions:


GET /v2/webhooks

Returns a list of all webhook subscriptions for the authenticating scope.

curl \
  --url 'https://api.loyaltylion.com/v2/webhooks' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

POST /v2/webhooks

Create a new webhook subscription. You must provide a JSON request body containing the topic and address for the new webhook subscription. See webhook topics for a list of available topics.

The address must be HTTPS.

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/webhooks' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "webhook": {
      "topic": "customers/update",
      "address": "https://app.example.com/loyaltylion/webhooks"
    }
  }'

DELETE /v2/webhooks/:id

Delete an existing webhook subscription by id.

curl -X DELETE \
  --url 'https://api.loyaltylion.com/v2/webhooks/7291' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

Webhook topics

The following topics are available for webhook subscriptions:

customers/update

Customer update webhooks are fired anytime a customer changes in LoyaltyLion. Examples of when this could fire include earning/redeeming points or moving into a new loyalty tier.

To subscribe to the customers/update topic your access token needs at least the read_customers scope.

Example webhook event:

{
  "id": "bff1bddb-6cd8-4c2c-9619-18744657053c",
  "topic": "customers/update",
  "created_at": "2018-01-01T03:00:05.000Z",
  "payload": {
    "customer": {
      "id": 6932,
      "merchant_id": "2134606599",
      "email": "jessica@example.com",
      "points_approved": 200,
      "points_pending": 300,
      "points_spent": 500,
      "rewards_claimed": 5,
      "properties": {
        "name": "Jessica White"
      },
      "metadata": {},
      "birthday": "1990-01-29",
      "blocked": false,
      "guest": false,
      "enrolled": true,
      "enrolled_at": "2015-12-10T03:00:00.000Z",
      "referral_id": "a4e",
      "referred_by": {
        "id": 3958,
        "merchant_id": "192838592"
      },
      "loyalty_tier_membership": {
        "started_at": "2017-03-03 00:00:00Z",
        "expires_at": null,
        "manual": false,
        "loyalty_tier": {
          "id": 1,
          "name": "Bronze",
          "position": 0,
          "default": true,
          "hidden": false,
          "lower_bound": "0.00",
          "upper_bound": "200.00"
        }
      },
      "insights_segment": "Loyal",
      "referral_url": "https://prz.io/KzByQ2Fa",
      "created_at": "2016-12-10T03:00:00.000Z",
      "updated_at": "2018-01-01T03:00:00.000Z"
    }
  }
}

loyalty_emails/unsubscribe

To subscribe to the loyalty_emails/unsubscribe topic your access token needs at least the read_unsubscribes scope.

Unsubscribe webhooks are fired anytime a customer unsubscribes from Loyalty Emails.

Request body

Our webhook request will include a JSON body:

Example webhook event:

interface UnsubscribeRequestBody {
  // a globally unique ID for this webhook event
  id: string
  // event that triggered this webhook
  topic: string
  // an ISO 8601 string representing the date this webhook was sent
  created_at: string
  // a resource-specific payload
  payload: {
    unsubscribe: {
      customer: {
        // the LoyaltyLion id for the customer who has unsubscribed
        id: number
        // the email address for the customer who has unsubscribed
        // you should add this address to your own unsubscribe list
        email: string
      }
    }
  }
}