Webhooks are a widely supported method used to allow multiple applications to interact with each other, using HTTP POST requests to pass callbacks between them. For more information, see Wikipedia's page on webhooks. Common uses for webhooks include sending notifications via email or SMS, posting messages to social media, automatically writing records to a spreadsheet, and updating enterprise databases.
Starting with Survey123 for ArcGIS 3.0, webhooks can be set up and activated when a survey response is submitted. For example, after a successful submission of information to the feature layer, the webhook could be called and trigger another action, such as sending a notification email, appending the survey content to a spreadsheet, and sending an alert.
Your workplace may have its own webhook provider, but a wide variety of third-party workflow services are available, such as Integromat, Microsoft Flow, Zapier, and tray.io. All of these can be used to incorporate Survey123 as a trigger for a greater automated process. In particular, Integromat and Microsoft Flow have a Survey123 connector, allowing you to integrate Survey123 into your webhook workflow with minimum difficulty, and without the need to configure the webhook in the Survey123 website or to input a payload URL.
The following sections demonstrate how to set up a notification webhook to send an email when a response has been sent that contains a question answered with a certain value.
There are endless ways you can use Survey123 as a trigger in your workflows. To get started, Integromat has templates that you can use to include attachments in your email notifications, add records to spreadsheets, and create calendar items.
If the survey you apply a webhook to has already been downloaded in the Survey123 field app, it will need to be downloaded again for the webhook to work.
Set up a webhook in Integromat
Integromat is an online automation platform. Sign up for a free account to get started.
- Go to https://www.integromat.com/ and sign in.
- Click the Create a new scenario button.
- Search for and select Survey123. Click Continue.
The Survey123 module is listed as a favorite in your scenario.
- Click the module icon in the middle of the screen and select Survey123 from the menu.
- Choose the When a survey response is submitted trigger.
The scenario icon changes color, and a wizard appears to help you configure the Survey123 module.
- Click Add and enter a name for your webhook. This name should be unique to the survey you are configuring the webhook for.
- If this is your first time using this connector in Integromat, click Add and name your connection to ArcGIS. Sign in to your ArcGIS organization. You only need to do this once, as Integromat will save your information for future use.
- Choose a survey from your ArcGIS organization to connect to.
- Consider the options to include in your webhook, and click Save.
Keeping the default value of Yes is recommended for all options, giving you the most flexibility when customizing your webhook.
- Click OK.
You now have your Survey123 module configured.
- Click the side of the Survey123 module to connect another module to it.
- Search for and select Gmail.
- Select the Send an email action.
- If this is your first time using this module in Integromat, click Add and name your connection to Gmail. Sign in to your Gmail account. This is the account that triggered emails will be sent from. You only need to do this once, as Integromat will save your information for future use.
- Add a recipient email. This is the email address that the triggered email will be sent to.
- Click in the subject text box. Use the module settings panel that opens to choose fields from your survey to construct your email subject.
- Click in the content text box. Use the module settings panel that opens to choose fields from your survey to construct your email content. Define the content using HTML.
- Click OK. Your webhook is now created.
- This scenario needs to send the email when a question has been answered a certain way, so the next step is to provide a filter. Click the spanner icon next to the dots that join the two modules, and select Set up filter.
- Click in the Condition text box and choose the field from your survey that you want to use in the filter.
- Choose the operator for the condition. In this case, choose the default, Equal to.
- Enter the value of the question on which you want to send the notification.
- Click OK.
Optionally, you can click Run once to test your webhook before publishing. After clicking Run once, open Survey123 and submit a survey, ensuring you use the condition that you defined in the webhook. Verify that the email arrives to the recipient.
- Click Scenarios in the Integromat main menu and use the on/off switch to activate your webhook.
To learn more ways to use Survey123 as a trigger in your workflows see Integromat.
Set up a webhook in Microsoft Flow
Microsoft Flow is a webhook service provided in the Microsoft Office 365 platform.
- Open Microsoft Flow.
- Select My flows in the page side menu.
- Select Create from blank from the New menu.
- Click the Create from blank button.
- The first step to creating your flow is to select a trigger. Type Survey123 in the search bar, which returns options for potential triggers. Select When a survey response is submitted.
- If this is your first time using this connector in Microsoft Flow, click Sign In to sign in with your ArcGIS organization credentials. You only need to do this once, as Microsoft Flow will save your credentials for all future uses of this connector.
- Select the survey you want to use for your webhook from the drop-down list of available surveys.
You have now set up the trigger for your webhook. However, for the webhook to perform any actions with this trigger, your process needs more steps.
- This workflow needs to send an email when a question has been answered a certain way, so the next step is to provide a condition. Click the New Step button, and choose Condition on the top of the Actions section.
- Click the leftmost text box to open a dialog box to select any field in your feature service. Select the survey question you want to use to qualify your survey.
- The middle text box is a drop-down menu to select the condition on which to trigger. Since you're looking for an exact response, select is equal to.
- In the rightmost text box, type the value for the question on which you want to send a notification.
- You want to send an email only if the condition is fulfilled, so click Add an action in the If yes box. The If no box remains blank.
- Multiple mail services have available connectors and can be used in this scenario. For this exercise, select Office 365 Outlook - Send an email.
- Sign in to the mail service with your credentials, if your credentials are not already saved.
- Only the To field of your email is required for the connector. Fill in the rest in a way that will be easily recognizable and that contains relevant information. The dialog box that appears when you select a text box allows you to insert the contents of the survey response as necessary.
- When your email is complete, click Save.
Your webhook is now complete and is active by default. The webhook will now execute every time a survey response is submitted with the given conditions.
Configure a webhook in the Survey123 website
- Open the Settings tab for your survey by selecting it from the menu in the lower right of the survey's panel in your My Surveys page.
- Select the Webhooks section from the menu on the left.
This page allows you to set and access all webhooks you've already set up. If you haven't set up any webhooks in Survey123, the page will be empty.
- Click Add Webhook. A new page opens to set up how the webhook will interact with your survey.
- Provide a name for your webhook, which will be used to identify your webhook in the future.
- The payload URL is where the survey information will be sent. This needs to be provided by an external webhook service.
- The trigger events describe what specific actions will call the webhook. Select New record submitted.
- Event data allows you to choose what information from your survey will be included in the payload: Survey info, Server response, Submitted record, User info, and Portal info. For the purposes of this exercise, check the Survey info and Submitted record options.
- The Status switch determines whether this webhook will be active when saved. By default, this is set to On.
- Click Save.
The webhook is now ready to use and will execute every time a survey response is submitted. Rules set within the webhook provider can ensure that an email is sent only if certain criteria are met.