Skip to content
Survey123 webhook flow
Use webhooks to automate your workflows and integrate ArcGIS Survey123 survey responses with other systems.

A webhook is a mechanism that pushes real-time notifications from a feature service to an endpoint you created that is listening for ArcGIS Survey123 events. ArcGIS Survey123 supports integration with webhooks and pushes updates to a hosted feature layer in your ArcGIS Online or ArcGIS Enterprise portal. You can use webhooks to create custom tasks to perform operations such as notifying and sending messages to applications after a survey is submitted, updated, or deleted.

When Survey123 updates a hosted feature layer, you can use webhooks to perform operations such as:

  • Send email notifications when surveys are submitted.
  • Send Slack notifications when surveys are updated.
  • Send Microsoft Teams notifications when surveys are deleted.
  • Connect with enterprise systems to update databases or spreadsheets.
  • Build conditional workflows to automate tasks based on survey responses.

Prerequisites

To use webhooks in ArcGIS Survey123:

You need an ArcGIS Online or ArcGIS Enterprise account with:

  • Administrator role, Publisher role, or Owner of the hosted feature layer.
  • Non-admins with update control rights (from a shared update group) can also create webhooks.
  • Access to ArcGIS Survey123.
  • Permission to create and manage surveys.

You need a webhook endpoint that:

  • Accepts HTTP POST requests.
  • Returns HTTP status codes.
  • Handles JSON payloads.
  • Is publicly accessible.

How to automate workflows with webhooks

To automate workflows with webhooks, you configure HTTP endpoints that receive real-time notifications when survey events occur. These endpoints can process survey data, trigger automated actions, and integrate with external systems to create seamless workflows that eliminate manual data transfer and processing.

The general steps to automate your custom workflows with webhooks are:

  1. Create an HTTP endpoint that can receive and process webhook notifications.

    • You can use a webhook receiver, a webhook service, or a webhook proxy. Learn more about how to create a sample webhook receiver in the Code Examples section.
  2. Configure a webhook in one of three locations:

    • Organization > Settings > Webhooks (for administrators)
    • My Settings > Webhooks (for non-administrators)
    • Item Details Page > Settings > Webhooks (for hosted feature layers)
  3. Test and monitor your webhook by submitting a Survey123 survey through the Survey123 Field App or the Survey123 Web App.

Webhook event types

Survey123 webhooks support the following event types:

Event TypeDescriptionWhen Triggered
addDataNew survey response submittedWhen a survey is completed and submitted
updateDataExisting survey response modifiedWhen a submitted survey response is edited
deleteDataSurvey response deletedWhen a survey response is removed

Payload structure

Survey123 sends this JSON structure to your endpoint. The contents of the payload will differ based on your survey configuration and the event type:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "eventType": "FeaturesCreated",
  "portalInfo": {
    "name": "ArcGIS Online",
    "url": "https://www.arcgis.com"
  },
  "surveyInfo": {
    "name": "Field Inspection",
    "id": "123456",
    "formItemId": "form-item-id",
    "formTitle": "Form Title",
    "serviceItemId": "service-item-id",
    "serviceUrl": "service-url"
  },
  "userInfo": {
    "username": "inspector1",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "email": "john@example.com"
  },
  "feature": {
    "attributes": {
      "inspection_type": "safety",
      "status": "failed",
      "notes": "Requires immediate attention",
      "globalid": "{FB29BDB9-79DD-4A7E-882A-A7B5B1932320}",
      "objectid": 57
    },
    "geometry": {
      "x": -122.84153767025904,
      "y": 49.18022516016153,
      "spatialReference": { "wkid": 4326 }
    }
  }
}

Code Examples

Below are practical examples showing how to implement webhook automation for common Survey123 scenarios:

Sample webhook receiver

When you implement a webhook receiver, you can use a basic Python Flask app to receive and log webhooks. Here is an example of a webhook receiver:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

@app.route('/webhook', methods=['POST'])
def survey123_webhook():
    data = request.json
    logging.info(f"Received webhook: {data}")

    # Add your processing logic here

    return jsonify({"status": "success"}), 200

if __name__ == '__main__':
    app.run(port=5000)

Store survey responses in a database

Example of storing survey responses in a PostgreSQL database:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
from flask import Flask, request, jsonify
import psycopg2
import json
from datetime import datetime

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def store_survey():
    data = request.json

    # Validate required fields
    if not data or 'surveyInfo' not in data or 'feature' not in data:
        return jsonify({"error": "Invalid payload"}), 400

    # Extract survey data
    survey_id = data['surveyInfo']['id']
    attributes = data['feature']['attributes']

    # Connect to database
    conn = psycopg2.connect(
        dbname="your_database",
        user="your_user",
        password="your_password",
        host="your_host"
    )
    cur = conn.cursor()

    try:
        # Insert survey response (serialize attributes as JSON)
        cur.execute("""
            INSERT INTO survey_responses
            (survey_id, response_data, created_at)
            VALUES (%s, %s, %s)
        """, (survey_id, json.dumps(attributes), datetime.now()))

        conn.commit()
        return jsonify({"status": "success"}), 200

    except Exception as e:
        conn.rollback()
        return jsonify({"error": str(e)}), 500

    finally:
        cur.close()
        conn.close()

Send email notifications

When a survey is submitted, you can send an email notification to a recipient. Here is an example of sending email notifications when surveys are submitted:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
from flask import Flask, request, jsonify
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from datetime import datetime

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def notify_submission():
    data = request.json

    # Validate required fields
    if not data or 'surveyInfo' not in data or 'userInfo' not in data:
        return jsonify({"error": "Invalid payload"}), 400

    # Extract survey info
    survey_name = data['surveyInfo']['name']
    username = data['userInfo']['username']

    # Email server settings
    smtp_server = "smtp.your-server.com"
    smtp_port = 587
    sender_email = "your-email@domain.com"
    password = "your-password"
    recipient = "recipient@domain.com"

    # Create email content
    subject = f"New Survey Submission: {survey_name}"
    body = f"""
    New survey response received:
    Survey: {survey_name}
    Submitted by: {username}
    Time: {datetime.now()}
    """

    try:
        # Create and send email
        message = MIMEMultipart()
        message["From"] = sender_email
        message["To"] = recipient
        message["Subject"] = subject
        message.attach(MIMEText(body, "plain"))

        with smtplib.SMTP(smtp_server, smtp_port) as server:
            server.starttls()
            server.login(sender_email, password)
            server.send_message(message)

        return jsonify({"status": "success"}), 200
    except Exception as e:
        return jsonify({"error": str(e)}), 500

Send Slack notifications

When a survey is submitted, you can send a Slack notification to a channel. Here is an example of sending Slack notifications when surveys are submitted:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from flask import Flask, request, jsonify
import requests
from datetime import datetime

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def notify_slack():
    data = request.json

    # Slack webhook URL
    slack_webhook = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

    # Format message
    message = f"""
    :clipboard: *New Survey Response*
    *Survey:* {data['surveyInfo']['name']}
    *Submitted by:* {data['userInfo']['username']}
    *Time:* {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
    """

    try:
        response = requests.post(slack_webhook, json={"text": message})
        if response.status_code == 200:
            return jsonify({"status": "success"}), 200
        else:
            return jsonify({"error": "Failed to send to Slack"}), 500
    except Exception as e:
        return jsonify({"error": str(e)}), 500

Best practices

Follow these essential best practices to create effective webhook automation workflows:

  • Validate webhook payloads and check for required fields before processing
  • Use proper error handling with try-catch blocks and appropriate HTTP status codes
  • Process webhooks asynchronously to avoid timeouts and improve performance
  • Verify webhook source to ensure requests are coming from Survey123
  • Implement deduplication logic since webhooks may deliver events multiple times

Resources

Tutorials

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.