Webhooks are a simple way to notify external systems when a new participation happens within your campaigns. Details of the participations will be sent in real time to a URL you specify.
Webhooks can be thought of as push notifications. Rather than requiring you to pull information via an API, webhooks will push information to your endpoint.
Currently, Qualifio’s webhooks have one supported trigger, which is for each new participation. When a new participation occurs, Qualifio will send a notification (HTTP POST request) containing information about the completed participation (JSON body) to the endpoint you specify.
A participation is considered completed when the participant reaches the end screen of the campaign. This may lead to data discrepancies between Qualifio statistics and your webhook.
When configuring webhooks, you may select the version of webhooks to use. Currently supported versions:
- Webhook 1.0 – Fore more information, see Using webhooks 1.0
This version is considered deprecated as of February 9, 2021.
- Webhook 2.0 includes the following:
- You can add an authentication header. The webhook requests you receive will contain your required key and value.
- Version 2.0 has a richer payload that is more comprehensive than in version 1.0. It includes data from the questionnaire and the exit screen (score, profile, prizes, etc.)
- To help you make a smooth migration to this new webhook, we have a migration guide: Getting started with the webhook 2.0.
- Go to the Webhook 2.0 page in Qualifio. You may access it from the Settings menu, under Integrations & partners.
- In the Webhook 2.0 page:
a. Name of this integration: enter a display name for the webhook.
b. Webhook host: enter the URL to which webhook notifications will be sent when a participation occurs.
c. Once you've added your new webhook, select Save.
By default, the maximum limit is one webhook per account or per website. If you need to use different webhooks in each of your campaigns, you may configure the platform to do so. Please make contact with your Qualifio Expert or with our Helpdesk.
Webhook authentication workflow
Webhooks require that your notification URL is accessible to Qualifio’s systems. However, we realise that you might not want this URL publicly accessible, for security reasons.
This is why you can choose to authenticate the notifications using the webhook header, in which case you should enter the name (key) and value.
These credentials will be sent together with the webhook notification, allowing you to verify that incoming requests originate from Qualifio.
Note: It is also possible to whitelist the IP addresses from which you will get the webhook callback. All Qualifio webhook requests originate from a static set of IP addresses:
If you want to customise where your webhook is enabled, please see Manage data pushes. A common case is triggering a webhook or push only when a participation occurs on a specific website or in specific campaigns.
In the Settings step of your campaigns, you can see a list of your active pushes. To add or change this, you must be a user with the Admin role.
Webhook endpoints receive a JSON-formatted payload containing the following fields: https://integrations.qualifio.com/schemas/webhook/v2/index.html
Don’t forget you can create mapping variables and link them to your questions, form fields and opt-ins in order to easily retrieve the different values in the webhook payload.
Testing webhooks: helpful tips
It’s often helpful to test webhooks. Though we don’t offer a native feature for testing webhooks, there are a variety of free services that you can use to send and view webhook requests. One we like is webhook.site. You can get an endpoint there, configure Qualifio to send webhooks to that URL, then review the full request.
Additional information & troubleshooting
Ok, everything is set up. What could possibly go wrong?
- Webhook settings can be cached for up to five minutes. When making changes to the webhook URL, authentication credentials, or other settings, it may take up to five minutes to see your changes go into effect.
- We send you one notification per request. So, when a lot of participations have occurred within a short period of time, keep in mind that all those events might delay the push of your data. We do not guarantee that you get these notifications in real time.
- Discrepancies between Qualifio statistics and pushed data: you may notice differences in data collected through Qualifio statistics (campaign statistics or Global Stats) and data obtained through webhooks. That is because Qualifio statistics consider a participation as completed provided that its form was submitted (identified campaigns), while webhooks consider a participation as completed when the exit screen has been shown.
That’s it for the big picture. This page has no pretension to be exhaustive but much more to be an introduction to this solution. For more information about working with the webhook 2.0 or if further clarification is needed, let us know.