Webhook 2.0 overview

Tabata Vossen -

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 completed participation (JSON body) to the endpoint you specify.

Tip
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.
Admin users can create and manage webhooks. Other users cannot create/manage webhooks.

Versions

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:
In this article, we focus on our webhook 2.0. If you want to learn about our webhook 1.0, then you can do it here.

Webhook setup

From here you have a range of options, from using Zapier or Blendr to working with a developer or a cool coworker who loves digging into code.

  1. Go to the Webhook 2.0 page in Qualifio. You may access it from the Settings menu, under Integrations & partners.
  2. In the Webhook 2.0 page:

Screenshot_2021-01-19_at_16.05.09.png

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.

⚠️ To secure your webhook, we recommend you use an HTTPS URL for your webhook endpoint.

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

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

Tip
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 

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