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.
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.
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.
The webhook request body will be a JSON
object containing webhook metadata and
the event-specific payload.
Unique ID for this webhook event, which can be used to deduplicate events
The topic of the webhook event
An ISO 8601
timestamp representing the date this webhook was sent. This
may be different from the date the event occurred
The event-specific payload as a JSON object. See the respective page in the documentation for each event for a description of its payload.
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:
Example code to verify a webhook:
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.
Failed webhook events are retried with an exponential backoff until a success response is received or the webhook subscription is removed: