Skip to main content

Webhook 2.0

The webhook 2.0 allows you to send automated messages from Qualifio to your external application in real-time (such as Zapier for example).The message contains information about qualifio campaign participations, partial or fully completed. Since the webhook 2.0 is a Qualifio standard integration, we encourage you to use it to collect participations data.

Overview​

HTTPS protocol​

The webhook sends the participations to the endpoint URL via HTTPS POST calls. Your servor needs to be able to handle such requests.

Payload structure​

The participation data is sent within a payload containing all data related to the campaign and the participation (questions, form data, game data...).The format of the payload is a JSON and its structure is fixed. The JSON payload is the following:

info

Push trigger​

Push conditions are set up in Qualifio back-office and define the trigger to send the data. Indeed, as incomplete participation can be collected,the sending of an incomplete participation will be triggered after 60 minutes following the start of the campaign. Complete participations will be sent when submitting the form or the questions.

Security​

Webhook 2.0 can be secured by using different known authentication methods such as Basic Auth , Bearer Auth or by using a custom header with a custom value.

Eg :

  • Header name : x-test-authorization-header
  • Header value : 123456ots

Moreover, an extra layer of security can be configured:

  • Secret : It allows you to generate an HMAC signature, combination of the secret and the participation payload in the header
curl \
 --request POST \
 --header "Content-Type: application/json" \
 --header "x-test-authorization-header: 123456ots" \
 --data 'the payload of the participationin JSON' \
 https://www.google.com

Response and retry management​

A participation is considered successfully received by the configured endpoint if a 2XX status code is returned in response to the POST request sent for that campaign participation. A participation can be successful even if it is incomplete; this will depend on the push condition you define.

If any code other than a 2XX status code is received in response to the POST request, the call will be considered failed.

Thanks to the standard retry process, the HTTPS POST request will be retried up to 7 times before being completely blocked. The retries occur after 1 minute and then regularly until 24-26 hours after the initial attempt. The only exceptions to this retry process are when the HTTP status codes are 400, 401, 403, 404, or 405, in which case retries will not be performed.

If the service remains unavailable after this 24-26 hour period, the call is considered failed and cannot be automatically retried.

Then the only way to retrieve the data is through a manual export to be set up within the back-office.

How to test ?​

You can test the webhook 2.0 by playing a campaign and configure your endpoint as a webhook.site.

Additional ressources​