T.V
- 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.
See exactly what the webhook payload looks like.
About webhooks
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.
Ready to get started with Qualifio webhooks? Our first recommendation is to watch this video on what webhooks are and follow along as we show you how to receive Qualifio webhooks with your application.
Webhook setup
You have a range of options, from using Zapier to working with a developer or a cool coworker who loves digging into code.
- Go to the Webhook page in Qualifio. You may access it from the Integrations menu, under Integrations.
- 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. To secure your webhook, we recommend you use an HTTPS URL for your webhook endpoint.
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 setup.
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.
Webhook management
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 payload
See exactly what the webhook payload looks like.
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 (under the "variables" object).
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, and 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 30 minutes. When making changes to the webhook URL, authentication credentials, or other settings, it may take up to 30 minutes to see your changes go into effect.
- You will receive one notification per participation. 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. Keep on learning and explore our developer documentation on managing your webhooks.
For more information about working with the webhook or if further clarification is needed, let us know.