Receiving Webhooks

A webhook is an HTTP callback: when one of the events it subscribes to happens in your loyalty program, we send an HTTP POST request with the event to the webhook's URL. Use webhooks to extend your loyalty program, for example to update a CRM, send email notifications, or integrate with wallets or account credits. Every event is described in the Loyalty Webhooks Reference.

Configuring a webhook

1. In the Admin Console, go to Notifications and click Webhooks.

2. Click Create Webhook and fill in the webhook's configuration:

   Field	Description
   Webhook Name	A name for your webhook.
   Webhook URL	The endpoint the events are posted to.
   Secret Key	The webhook's secret key, used to sign the requests.
   Events to send Webhook for	The events you want to receive: transaction, member, referral, system and campaign events.
   Batch size for bulk events	How many events a single request can carry for bulk events.

3. Click Save Webhook.

You can create up to 10 webhooks, each with its own URL, to send different events or categories of events to different endpoints.

The request

The body of the request is a JSON document that carries a batch of events, so that one request can deliver several events at once. Each event includes its data, such as the member and, for transaction events, the transaction:

{
  "request_id": "61f11851bdfb9aac526d0c70",
  "total_count": 2,
  "created_date": "12/29/2021 16:47:41",
  "events": [
    {
      "id": "61f1dfbd0c709aac1851b526",
      "event_type": "event_points_earned",
      "data": {
        "member_info": { "...": "The member" },
        "transaction_info": { "...": "The award transaction" }
      }
    },
    {
      "id": "507f1f77bcf86cd799439011",
      "event_type": "event_points_earned",
      "data": {
        "member_info": { "...": "The member" },
        "transaction_info": { "...": "The award transaction" }
      }
    }
  ]
}

Member events, such as a member enrolling, carry member data, while transaction events, such as points being awarded, redeemed or deducted, carry the details of the loyalty transaction.

Batch size

For bulk events, you can choose how many events a single request carries. In the Admin Console, go to Notifications >> Webhooks and select the batch size for bulk events.

Responding to a webhook

Return a 200 status code to acknowledge receipt of the events. Any other status code is considered a failure, and the request is sent again every 5 minutes until your endpoint returns 200 or the maximum number of attempts is reached (5 by default). Your Customer Success Manager can change these settings.

Best practices

• If your endpoint runs complex logic or makes network calls, the request may time out before it finishes. Return 200 as soon as you receive the request, then process the events.
• Your endpoint may occasionally receive the same event more than once. Log the IDs (events[].id) of the events you've processed, and skip the ones you've already logged.
• Before processing a request, verify its signature to make sure it was sent by TrueLoyal.

Webhook status

A webhook is in one of three states:

• Enabled: the webhook is active and receives events.
• Paused: the webhook failed too many times and was paused automatically. While it's paused, new events are marked as failed and aren't sent to its URL.
• Disabled: the webhook was disabled and doesn't receive events.

To enable a paused or disabled webhook, click Enable Webhook. Fix the errors that caused a webhook to be paused before enabling it again. TrueLoyal emails the program's administrators about every failed request and paused webhook.

To disable or delete a webhook, go to Notifications, select the webhook, click Action, then Disable or Delete.

Retrying failed requests

Failed requests are retried automatically every 5 minutes until your endpoint returns 200 or the maximum number of attempts is reached. After that, you can retry them manually. If the webhook is paused, enable it first, then:

1. Go to the Webhook Logs section.
2. Select the Failed tab.
3. Select the failed events you want to send again.
4. Click Retry Selected Logs.