A webhook is a user-defined HTTP callback that is called each time a response is received for a survey, making it simple to achieve run-time integration of response data in your own or other systems. You can configure a webhook at the site-level and/or at the survey-level. Webhooks configured at the site-level are used for all surveys of that site, except when explicitly overridden at the survey-level.

Webhooks are configured on the "Settings" page of a site or survey, in the "Webhooks Integration" panel. Here you can specify the URL where the response data will be posted to, using an HTTP request. You can specify an HTTP or an HTTPS URL. You can also specify whether the data will be send in JSON or XML format. For ease of definition we specify the sent objects as C# classes, which will be serialized to either JSON or XML in the data that is sent to the webhook end-point.
The Webhooks integration sends an object of type WebhookData. This object contains a list of Response objects that are also used - and defined - by our REST Reporting API (see section "Returned objects").

class WebHookData                       // Data that is sent to a webhook end-point.
{
    string              ApiKey;         // The Informizely API Key.
    string              Secret;         // MD5 Hex of "<API Key>:<API Secret>".
    string              SurveyId;       // The survey ID.
    Response[]          Responses;      // List of 'Response' objects. Defined on the REST Reporting API page.
}

The 'ApiKey' and 'Secret' properties can (but don't have to) be used by the receiving end-point to validate that the request was sent by the Informizely server. The 'Secret' consists of the MD5 Hex of your API Key and API Secret, separated by a ':'. These can be found on the "My Account" page in your dashboard, if your subscription plan allows usage of the Webhooks integration or the REST Reporting API. If no API Secret has been set, you can click the "Generate" link to create one.

Note that both the 'SurveyId' and the 'Responses' properties can be null. When you configure a webhook at the site-level, a test request is performed where both the 'SurveyId' and the 'Responses' properties have the value null. When you configure a webhook at the survey-level, a test request is performed where the 'Responses' property has the value null.

Note that 'Responses' can contain more than one Response object. This can be the case for example when multiple failed requests are retried at a later time, or when the site admin requests to (re-)send all survey responses (in the survey's Webhook Integration panel). Because of this last possibility we recommend to make sure that the receiving server allows for receiving data for the same response multiple times. Informizely uses the HTTP response code to determine wether a webhook call was succesful. All codes in the 200-299 range are interpreted as "success", all other codes are interpreted as "failed". Failed webhook calls are shown in a survey's "Webhooks Integration" panel. Failures are retried after a next successful webhook call. They can also be retried manually in the Webhooks panel. If there are too many errors in a sufficient enough amount of time the Webhook will be disabled and has to be manually enabled when the receiving end-point is available again. It may be necessary to manually (re-)send all survey responses after a succesful re-enablement, in order to bring the webhook end-point up-to-date. Each time when a webhook configuration is changed and the webhook is enabled, a test WebhookData object with an empty 'Responses' property is sent to the end-point, in order to test the URL. If a HTTP response code in the 200-299 range is returned the webhook will be enabled. If your webhook end-point uses Basic Authentication, you can specify the 'username' and 'password' fields in the webhook URL as follows:
http(s)://username:password@yourserver/webhook-end-point

See also: REST Reporting API