A webhook enables you to pass data to another system and trigger a response to an event. In Qualifio Loyalty, you can use webhooks to receive notifications about events that happen in your program, such as a member earning points or moving to a new level.
It works like this: when an event occurs, Qualifio collects data about the event, creates an event notification, and sends that notification to the webhook URL.
Technically speaking, for each event, Qualifio sends a POST request to your URL with the event details in JSON format.
Now we understand what a webhook is and how it typically works, why should you use it?
Why use webhooks
One of the best things about webhooks is that the data arrives in real time – which opens a lot of possibilities for you to build some really cool member experiences.
A few ways you can use webhooks include:
- Creating email notifications when an event occurs. For example, you can use a webhook to connect with your email marketing software so that your newest member gets an email to say “thanks for joining; you’ve just earned 10 loyalty points”. You could also let members know they reached a certain level or message them with their points balance on a monthly basis.
- Synchronising member data in other applications to keep external systems up to date. Our webhook payloads contain all data about the event which triggered a webhook, including information about the member, such as their ID and email address. This means that you can, for instance, send updated data to a CRM if a member’s birth date is changed.
How to set up webhooks
Before you start...
Define a URL to receive event notifications in your application, i.e. the URL your payloads will be sent to.
Zapier lets you send info between Qualifio Loyalty and webhooks automatically – no code required.
After you get the webhook URL from the application you want to send data to, it’s a three-step process:
Step 1: Create a webhook integration and specify the notification URL
Start off by configuring your first webhook using the Integrations hub. Qualifio makes it possible to define multiple webhooks.
Managing webhooks requires the Admin user role.
To create the integration, perform the following steps:
- Open the Account settings and choose Integrations.
- Click on the Set up an integration button.
- Enter a name for the webhook.
- In the Global variables tab, provide the notification URL.
Qualifio can optionally sign the webhook events it sends to your endpoint by including a signature in each event's header. Specify a secret to verify the events that Qualifio sends to your webhook endpoints.
From the same page, you can now activate your webhook by sliding the "Active" toggle in the upper right corner to the ON state (the toggle will turn blue).
Step 2: Manage push rules and subscribe to event notifications
Secondly, you need to specify the events that you want to be notified about.
To subscribe to notifications about member actions, perform the following steps:
- Open the Account settings and click Push rules.
- Select a program. Note that push rules are program-specific. The configuration you supply can apply to one or more programs.
- In the Events column, choose the type of events you want Qualifio to notify you about.
- Under Push destinations, select one or more integrations.
- Click the add button.
- Click Save.
The following events are available for webhook subscriptions:
- Profile created is fired when a member joins the loyalty program.
- Level changed is fired when a member moves up or down a tier.
- Points earned is fired when a member earns points.
- Points burned is fired when a member redeems their points to claim a reward.
- Points changed (+) is fired when a member’s point balance is manually adjusted for a positive amount (credit).
- Points changed (-) is fired when a member’s point balance is manually adjusted for a negative amount (debit).
- Reward offered is fired when a member is offered a free reward (via the CRM).
- Identifier added is fired when a new identifier is added to a member profile. Example: when a member links their Facebook account via the social media widget, Qualifio retrieves their Facebook ID and adds it to their CRM profile.
To learn more about payload details, see Loyalty webhooks.
Step 3: Trigger an event and check the logs
From now on, Qualifio will issue a POST request to the specified URL every time one of the selected events occurs.
To view the webhook event logs, log in as an admin user. Choose Account settings in the top menu, and then choose Event logs.
The event logs show you both the sent request and the received response. This monitoring system is useful for debugging webhook events.
Validate your webhook event notification
A non-Qualifio post can potentially compromise your application. Each webhook notification from Qualifio contains a signature in the header field:
The value of this header is a SHA256 signature generated using your webhook secret and the payload of the request.
You can validate the webhook notification by reconstructing the signature and comparing it to the one sent in the webhook header field. For more information, see Checking the webhook signatures.
To add an additional layer of security, you can do IP whitelisting. That mechanism will verify that webhook requests are coming from Qualifio. It is useful if your server blocks traffic from all IP addresses unless they’ve been whitelisted.