Previous Next

Webhooks allow web services to trigger actions, push data, or otherwise connect to other web services. Initially the exclusive domain of programmers who sought to use certain technologies and conventions to connect systems, webhooks are increasingly useful to non-programmers as well. You can use webhooks to publish incoming SurveyCTO form data to a wide variety of outside systems, but typically you will need some technical expertise and/or instructions from the receiving system in order to successfully configure everything.

You can get started by going to your server console's Export tab, scrolling down to the Advanced: publishing form and dataset data to the cloud section, and clicking the ON/OFF toggle to ON if you haven't already enabled cloud publishing.

To configure any one of your forms to publish via webhooks, click on the Configure option for that form, and then click Add Webhook in the panel that appears.

You'll first need to choose a good name for your webhook connection, based on the system to which you're publishing and what you intend to publish. After that, you'll need to select exactly which form fields to publish (but note that, for encrypted forms, only form fields that have been explicitly marked as publishable will be listed). There's a Select all button if you simply want to publish all fields.

Other options

Finally, you have a few other options available:

1. You can choose whether or not to include a hyperlink to the full submission in SurveyCTO, in the data that publishes to the webhook. (If you do include the hyperlink, and you happen to also be publishing a form field named "submission_url", choose a different name for the hyperlink.)
2. You can include one extra field, if you wish, as a text summary of the submission (e.g., as its title or alert text, depending on the system to which you're publishing). If you choose to include an extra field, you can choose its name and its contents; in its contents, you can use ${fieldname} references to include data from the submission being published, just like in a form label. For example, you might include a summary like "Submission received from ${enumerator_name}, for household headed by ${hh_head}". (Note, however, that you can only reference "publishable" fields in encrypted forms.)
3. You can choose to embed the contents of binary fields (files attached to submissions) in the data published to the webhook. If you don't choose to do so, file fields will simply publish as hyperlinks. (Note that you can't embed binary fields for encrypted forms.)
4. You can check Publish existing data if you want to publish existing form submissions. If you don't check this option, then only new submissions that come in (after you configure publishing) will publish to the webhook.

Publishing

As submissions come in to the server, your selected fields will be automatically published to your chosen webhook – but there will be a brief delay of up to ten minutes.

Previous Next