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

T.V -

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 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 loyalty 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.

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

Permissions
Managing webhooks requires the Admin user role.

To create the integration, perform the following steps:

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

Schermafbeelding_2022-12-07_om_14.15.48.png

Important
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:

  1. Open the Integrations and click Push rules.
    Capture d’écran, le 2023-12-18 à 14.03.17.png
  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 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 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.

Was this article helpful?

Can’t find the answer you need?

Send us a question and connect with an expert to get personal assistance.

Contact support

Vous ne trouvez pas les réponses que vous cherchez ?

Nous sommes là pour vous aider. Envoyez-nous une demande en direct !

Contacter le support
helpcenter experts