Web Hooks

A web hook allows you to call a web service in an external system when an event happens on the Smap server. For example when a submission is received a callback URL that you have specified can be called with the results of that submission.

Getting the callback URL

The external system you are going to call needs to generate the callback URL. There are many tools such as Zapier that can be used to do this. In this case when Smap calls the callback URL a Zapier workflow is started. This can process the data and send it to one of the thousands of different applications that have interfaces to Zapier.

User name and password

Smap supports basic authentication of webhook calls. Hence you can optionally add a user name and password. Often this is not required as callback URLs generally include a long sequence of random characters so as long as you do not publicise the URL it should be secure. For example here is a (slightly modified) callback URL generated by piped dreams:

Monitoring

Calls and their status, sucessfull or otherwise can be monitored on the Monitoring page in the Admin module. Select a source of "Notifications" and then specify Show as "last 200".

Data Submission Web Hooks

Adding

These web hooks are added on the notifications page which is in the tasks module. After clicking the Add button specify the target of the notification as a Web Hook. You will then be able to specify the callback URL and optionally a user name and password. The trigger of the notification can be set to:

  • Submission. New results submitted to the server.
  • Task Reminder. A task has not been completed within the alloted time.
  • Console update. The data has been changed using the console.

Filtering

Notifications are for specific surveys. You may also want to add a filter such as "${age} < 10", especially if you are receiving thousands of submissions per day. This can be particularly important if you are using paid middleware such as Zapier. You don't want to filter out 90% of the requests in your middleware when you are being charged each time the workflow is initiated. Hence pre-filtering in Smap will save you money.