Custom rewards

You can create custom rewards to perform actions or provide rewards that don’t fit into the standard LoyaltyLion reward types.

These rewards can be fulfilled in one of two ways: manually or via a webhook. This page explains how to use webhooks to fulfil custom rewards.

Reward redemption webhook

When a customer claims a reward, we’ll send a POST request to your URL containing a JSON payload of information about the reward and the customer who claimed it.

When we receive a 2xx status code, we’ll consider this reward fulfilled, so it’s important to only send a success response if you have actually fulfilled the reward, or saved it to process later.

If we receive any other status code, we’ll continue to retry the webhook until a 2xx code is returned, gradually increasing the time between attempts.

Request headers

The webhook we send contains the following headers:

Request body

Our webhook request includes a JSON body:

interface CustomRewardRequestBody {
  // true if this is a test webhook, false otherwise
  test: boolean
  // the LoyaltyLion id of the reward being redeemed
  reward_id: number
  // the identifier set by you when you create the reward
  reward_identifier: string
  // the LoyaltyLion id for the customer redeeming this reward
  customer_id: number
  // your internal id (from your ecommerce platform) for the customer redeeming this reward
  customer_merchant_id: string
  // email address, if present, for the customer redeeming this reward
  customer_email: string
}

Verifying the webhook

We sign each webhook with a signature which you can use to verify the request came from us and hasn’t been tampered with.

When you receive a request, you should generate your own signature using your LoyaltyLion secret and ensure it matches the one found in the x-loyaltylion-hmac-sha256 header.

To generate your own signature, create a HMAC using your LoyaltyLion secret and the raw request body. For example:

class WebhookController < ApplicationController
  LOYALTYLION_SECRET = 'secret'

  def handle_webhook
    verified = verify_webhook(
      request.raw_post,
      request.headers['x-loyaltylion-hmac-sha256'],
    )
    verified ? head(204) : head(422)
  end

  def verify_webhook(body, hmac)
    digest = OpenSSL::Digest.new('sha256')
    our_hmac = Base64.encode64(
      OpenSSL::HMAC.digest(digest, LOYALTYLION_SECRET, body),
    ).strip
    hmac == our_hmac
  end
end