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.

Webhooks are delivered with at-least-once delivery semantics. In rare situations you may receive duplicate webhooks. If strict exactly-once semantics are required, you can deduplicate events based on the id field in the webhook request body.

​
Request body

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

​
id
string

Unique ID for this webhook event, which can be used to deduplicate events

​
topic
string

The topic of the webhook event

​
created_at
string

An ISO 8601 timestamp representing the date this webhook was sent. This may be different from the date the event occurred

​
payload
object

The event-specific payload as a JSON object. See the respective page in the documentation for each event for a description of its 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