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 issues an HTTP POST request to the specified URL every time that event occurs.

The request body is 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: any
}

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

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

Responding to webhooks

Your app must acknowledge it received the webhook event by responding with an HTTP 200 OK within 5s.

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.

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 alert via the email address provided during your OAuth registration.

• After 30 failed attempts, the webhook subscription is removed and you are notified again.

Verifying webhooks

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:

• If you registered the webhooks with token/secret auth, your site secret
• If you registered the webhooks with an OAuth client, your OAuth client secret

Example typescript code to verify a webhook:

import crypto from 'crypto'

function validate(req: Request, secret: string): boolean {
  const requestSignature = req.headers['x-loyaltylion-hmac-sha256']
  const ourSignature = crypto
    .createHmac('sha256', secret)
    .update(Buffer.from(req.body))
    .digest('base64')

  return requestSignature === ourSignature
}

Managing webhook subscriptions

You can manage webhook subscriptions through our webhook API.

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 token & secret auth are never visible to OAuth clients.

Available actions:

• GET /v2/webhooks
• POST /v2/webhooks
• DELETE /v2/webhooks/:id

GET /v2/webhooks

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

curl \
  --url 'https://api.loyaltylion.com/v2/webhooks' \
  --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.

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/webhooks' \
  --header 'Content-Type: application/json' \
  --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 'Content-Type: application/json'

Webhook topics

The following topics are available for webhook subscriptions:

• customers/update
• loyalty_emails/unsubscribe
• program_events/customer.tier_upgraded
• program_events/customer.tier_downgraded
• program_events/customer.points_earned
• program_events/customer.reward_available_notification
• program_events/customer.recurring_reward_available_reminder
• program_events/customer.claimed_reward
• program_events/customer.referral_complete
• program_events/customer.rule_completed
• program_events/customer.approaching_tier_upgrade
• program_events/customer.moved_to_at_risk_segment
• program_events/customer.moved_to_defected_segment
• program_events/customer.moved_to_loyal_segment

customers/update

This webhook is 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 this webhook, your access token needs to contain the read_customers scope.

loyalty_emails/unsubscribe

This webhook is fired anytime a customer unsubscribes from loyalty emails.

To subscribe to this webhook, your access token needs to contain the read_unsubscribes scope.

program_events/customer.tier_upgraded

This webhook is fired when a customer moves up a tier.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

program_events/customer.tier_downgraded

This webhook is fired when a customer moves down a tier.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

program_events/customer.reward_available_notification

This webhook is fired when the customer has a new reward available. The available_rewards array contains rewards that are actionable, in stock, enabled and affordable by the customer.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

ⓘ As many customers redeem their points immediately after earning them, this event is only sent after a 5 minute delay.

program_events/customer.recurring_reward_available_reminder

This webhook is fired on a rolling interval, starting 1 month after you first register for it. It will fire for customers on the program who have not received a reward_available_notification within the same month. The available_rewards array contains rewards that are actionable, in stock, enabled, and affordable by the customer.

The points_approved_in_interval property contains the number of points the customer has earned within that month, and the points_interval_start_date describes when that month started.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

program_events/customer.claimed_reward

This webhook is fired when a customer has claimed a reward.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

program_events/customer.points_earned

This webhook is fired when the customer has earned points.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

ⓘ As many customers redeem their points immediately after earning them, this event is only sent after a 5 minute delay.

program_events/customer.referral_complete

This webhook is fired when a customer follows a referral link and completes an order.

To subscribe to this webhook, your access token needs to contain the read_customers and read_orders scopes.

program_events/customer.rule_completed

This webhook is fired when a customer completes an activity.

To subscribe to this webhook, your access token needs to contain the read_customers and read_orders scopes.

program_events/customer.approaching_tier_upgrade

This webhook is fired when a customer is close to moving up a tier.

To subscribe to this webhook, your access token needs to contain the read_customers scope.

program_events/customer.moved_to_defected_segment

This webhook fires when a customer moves to the Win Back insight segment. (Note that while the webhook contains the word ‘defected’, the segment is always referred to as Win Back).

To subscribe to this topic your access token needs to contain the read_customers scope.

program_events/customer.moved_to_at_risk_segment

This webhook fires when a customer moves to the At Risk insight segment.

To subscribe to this topic your access token needs to contain the read_customers scope.

program_events/customer.moved_to_loyal_segment

This webhook fires when a customer moves to the Loyal insight segment.

To subscribe to this topic your access token needs to contain the read_customers scope.