Webhooks - send real-time data from your program to your tools

A webhook enables you to pass data to another system and trigger a response to an event. In Qualifio account, 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 a notification, and sends that notification to your 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 points”. You could also let members know they reached a certain level or message them with their points balance every month.
• 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.

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 by configuring your first webhook using the Integrations hub. Qualifio makes it possible to define multiple webhooks.

To create the integration, perform the following steps:

1. Open the Integrations and choose Connectors.
2. Click on the Set up an integration button.
   
3. Enter a name for the webhook.
4. In the Global variables tab, provide the notification URL.

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:

1. Open the Integrations and click Push rules.
   
2. Select a program. Note that push rules are program-specific. The configuration you supply can apply to one or more programs.
3. In the Events column, choose the type of events you want Qualifio to notify you about.
4. Under Push destinations, select one or more integrations.
5. Click the add button.
6. Click Save.

The following events are available for webhook subscriptions:

• Profile created is fired when a member joins the 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 this FAQ about the 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 Testing in the sidebar 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.

Security

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:

X-Qualifio-Signature

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.

IP whitelisting

To add a 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.