Introduction

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.

​

Subscribing to webhooks

Use the Webhook API to view, subscribe and unsubscribe to webhooks.

Webhook subscriptions are scoped to the OAuth app (Client ID) that created them. That is, an OAuth client can only view their own webhook subscriptions. Webhooks created using API keys are never visible to OAuth clients.

​

Receiving webhooks

Once you have subscribed to a webhook, LoyaltyLion issues an HTTP POST request to the specified URL every time that event occurs. Some webhook events may have a cool-down period, which will be indicated on their documentation page.

​

Request body

The webhook request body will be a JSON object containing webhook metadata and the event-specific payload.

​

Verifying requests

The webhooks we deliver have a x-loyaltylion-hmac-sha256 header, which is a base64 encoded sha256 HMAC of the raw JSON request body and the relevant secret key:

• for webhooks registered with an an OAuth client, use OAuth client secret
• for other webhooks, use your site secret

Example code to verify a webhook:

import crypto from 'crypto'
import express from 'express'
import bodyParser from 'body-parser'

const LOYALTYLION_SECRET = 'secret'
const app = express()

function verifyWebhook(data, signature) {
  const ourSignature = crypto
    .createHmac('sha256', LOYALTYLION_SECRET)
    .update(data)
    .digest('base64')

  return ourSignature === signature
}

app.use(
  bodyParser.json({
    verify: (req, res, buffer) => {
      if (!verifyWebhook(buffer, req.get('x-loyaltylion-hmac-sha256'))) {
        throw new Error('Webhook verification failed')
      }
    },
  }),
)

​

Responding to webhooks

Your app must acknowledge it received the webhook event by responding with a 200 status code within 5 seconds.

When we see a response status outside the 2xx range, or a response isn’t received within the 5s timeout, that delivery is considered failed.

​

Webhook retries

Failed webhook events are retried with an exponential backoff until a success response is received or the webhook subscription is removed:

• After 5 failed attempts, you receive an email alert
  • For OAuth subscriptions, we’ll email the address you used to register the OAuth app. For other kinds of webhook subscriptions, we’ll email the owner of the LoyaltyLion account
• After 30 failed attempts, the webhook subscription is removed and you are notified again