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 participation (JSON body) to the endpoint you specify.
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:
- 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.)
- You can add an authentication header. The webhook requests you receive will contain your required key and value.
- When using the webhook 2.0, we recommend implementing signature verification on your end to validate the authenticity of the incoming requests. How to verify a signature
- 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.
- On the Webhook 2.0 page:
a. Name of this integration: enter a display name for the webhook.
b.Define how you want to deal with incomplete participations.
c. Webhook host: enter the URL to which webhook notifications will be sent when a participation occurs.
d. Authorisation header: you can add authentication to make your webhook more secure. To do this, add a name (key) and value before saving your webhook. Learn more about how to use webhook authentication: Webhook authentication and security
e. Webhook secret: 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.
f. 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.
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.