Webhooks make it possible to send response data from Pointerpro to any given API. This webhook system is the heart of our Zapier and Integromat integration, but can be used with other API’s if setup correctly. This document aims to explain what is necessary to setup such an API and what can be expected from the webhook integration.
The notifications are sent via an HTTP POST request, and the response data is presented in JSON format.
This guide will teach you:
1. Setting up Webhooks
Going to the Extra Options tab in your questionnaire. Scroll down to Integrations and click Webhooks.
You'll see where you can enter the webhook URL. This is the endpoint to which we will make the HTTP POST request to.
We recommend using HTTPS for your webhook URL because it is more secure
Click Save when you have entered the URL.
Once you've saved, you'll have the option to get example data to review the format of the response Webhook notification. This will fetch the last survey response received.
This is how the example data will be shown:
Click Save changes to save your work and you are done. Any new submissions will be automatically posted to the specified Webhook URL.
That's the basics covered, and you can also click view logs to display the 50 most recent results. Please note that Zapier integration logs will also be presented here for troubleshooting.
Here's how the logs will be shown:
Make use of the copy function to copy and paste out the Payload or Response status. Your webhook should send a 2XX HTTP response status code back to indicate webhook data receipt. 200 = Accepted
3. How it works
Here is how the webhooks work:
- As described above, Webhook is configured in the Pointerpro editor per survey
- A respondent submits the survey
- The response is saved
- A call is made to the API endpoint configured in the webhook with the response data in the payload
- The API endpoint can retrieve the response data
The webhook is activated after the response has been saved. You can expect the API call configured in the webhook to be made immediately after the response has been submitted, although a delay of a maximum of 60 seconds may occur sometimes.
4. Technical requirements API
These are the requirements of API endpoints that are used with the webhooks system:
- Public endpoint (no authentication)
- POST endpoint
- Returns 200 OK
You can use any language or any type of framework, as long as it can host a POST endpoint where Pointerpro can send the data to.
Here are some resources to get you started in some popular languages.
- NodeJS: https://stackabuse.com/building-a-rest-api-with-node-and-express/
- PHP (Laravel) https://www.tutorialspoint.com/laravel/laravel_request.htm
In case your endpoint returns an error, the call will automatically be retried a second time after 30 seconds. After two failed attempts, we will stop calling your API.
Logs of successful and failed attempts can be seen from the webhook settings in the questionnaire editor. From there you can also manually re-trigger a webhook call in case of a failure.
5. Payload data
The data that will be sent to the API endpoint configured in the webhook contains all details of the questionnaire response and is sent in JSON format. You can view an example JSON of the data in the webhook settings of your questionnaire after a first response has been submitted.
You can view a general example here:
https://s3-eu-west-1.amazonaws.com/surveyanyplace-docs/webhooks/webhook_example.json (last updated Nov 2017)
The JSON structure cannot be customized.