Webhooks

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.

---

---

This guide will teach you:

1. Setting up Webhooks
2. Notification
3. How it works
4. Technical requirements API
5. Payload data

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.

Click Save when you have entered the URL.

2. Notification

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:

1. As described above, Webhook is configured in the Pointerpro editor per survey
2. A respondent submits the survey
3. The response is saved
4. A call is made to the API endpoint configured in the webhook with the response data in the payload
5. 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.

What's next?

• Make allows you to automate many processes and simplifies the transfer of information between apps, saving you bags of time! Make offers similar features to Zapier but is more powerful as you can set a single event to trigger a number of different actions to be taken simultaneously.
• External fields allow you to pull in data from external data sources, such as a spreadsheet. This is useful if you want to read data from an external data source, for example, cell values from a Google sheet, use these values in variable data in the PDF report, or a more advanced use would be to use the Google sheet as a bi-directional database, whereby the same survey will also send data to the Google Sheet. This would allow the benchmark cell value referenced to be adjusted automatically as new responses are received.
• Google Tag Manager is a tag system that can be used for tracking and analytics on websites. It can be used to track respondents' behavior in your survey or to find out how effective an advert promoting your survey has been.