KoBoToolbox Trigger

Triggers when a KoBoToolbox form submission is received

Overview

Receives webhook notifications from KoBoToolbox when new form submissions are created. KoBoToolbox is an open-source data collection platform widely used for humanitarian field surveys, monitoring and evaluation, and research data collection. The trigger listens for form submission events on a specified form and delivers the raw submission data to the workflow. Supports optional reformatting of submission data including GeoJSON coordinate parsing, multiselect field splitting, and number type coercion via configurable field masks. Useful for automating data pipelines from field surveys, triggering notifications on new responses, syncing collected data to external databases, and building real-time dashboards from KoBoToolbox submissions.

Category: Productivity
Tool Name: kobotoolbox_trigger
Version: 1

Appearance: Icon: lucide-ClipboardList | Color: #2095f3

Node Type

Trigger — webhook (receives incoming HTTP callbacks)

Input / Output

Direction	Port(s)
Input	None (trigger node)
Output	Output

Credentials

This tool requires KoBoToolbox credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Form ID	string	Yes	—	The KoBoToolbox form/asset UID to listen for submissions on (e.g. aSAvYreNzVEkrWg5Gdcvg). Find this in the form URL or via the KoBoToolbox API.
Trigger On	options	Yes	formSubmission	Which event to trigger on. Currently only form submissions are supported.
				Options: formSubmission (On Form Submission)
Options	collection	No	{}	Additional options for processing submission data.
— Reformat	boolean	No	false	Whether to apply reformatting to the submission data, such as parsing GeoJSON coordinates, sanitizing key names (replacing ”/” with ”.”), and applying number/multiselect field masks.
— Multiselect Mask	string	No	select_*	Comma-separated list of wildcard-style selectors for fields that should be treated as multiselect fields (parsed as arrays by splitting on spaces). Only applied when Reformat is enabled.
— Number Mask	string	No	n_*, f_*	Comma-separated list of wildcard-style selectors for fields that should be treated as numbers. Only applied when Reformat is enabled.
— Download Attachments	boolean	No	false	Whether to download submitted attachments (photos, files) as binary data.
— Attachments Naming Scheme	options	No	sequence	How to name the binary attachment properties. (shown when Download Attachments is true)
				Options: sequence (e.g. attachment_N), question (use the original form question ID)
— Attachments Prefix	string	No	attachment_	Prefix for binary property names when using sequential naming. An index starting with 0 will be appended (e.g. “attachment_0”, “attachment_1”). (shown when Download Attachments is true and Attachments Naming Scheme is sequence)
— File Size	options	No	download_url	Attachment size to retrieve, if multiple versions are available. (shown when Download Attachments is true)
				Options: download_url (Original), download_small_url (Small), download_medium_url (Medium), download_large_url (Large)

Output Data

Each submission produces one output item. The submission fields are placed directly on the item alongside three metadata fields:

{
  "_trigger": "kobotoolbox_webhook",
  "_timestamp": "2026-01-01T00:00:00.000Z",
  "_webhookEvent": "formSubmission",
  "_id": 12345678,
  "_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "_status": "submitted_via_web",
  "_submission_time": "2026-01-01T00:00:00.000Z",
  "_validation_status": {},
  "_submitted_by": "field_agent",
  "_attachments": [],
  "_geolocation": [null, null],
  "_tags": [],
  "_notes": [],
  "formhub": { "uuid": "abc123def456" },
  "meta": { "instanceID": "uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "start": "2026-01-01T00:00:00.000Z",
  "end": "2026-01-01T00:00:00.000Z",
  "question_1": "Sample response",
  "question_2": "42"
}

• _trigger — always kobotoolbox_webhook.
• _timestamp — ISO 8601 timestamp of when the submission arrived.
• _webhookEvent — always formSubmission.
• Every other key comes from KoBoToolbox: your own question names carry the answers, and KoBoToolbox’s own bookkeeping fields (_id, _uuid, _status, _submission_time, _submitted_by, _validation_status, _attachments, _geolocation, _tags, _notes, formhub, meta) travel with them. Submitted attachments arrive as entries in _attachments carrying their download URLs and file metadata.

With Reformat enabled the shape changes, so write your downstream expressions against the reformatted keys:

• Group separators become nesting — a household/members/age field arrives as {{ $json.household.members.age }}.
• Leading and trailing underscores are trimmed from every key segment, so _id becomes id, _uuid becomes uuid and _submission_time becomes submission_time.
• Values that look like coordinates become GeoJSON objects: "lat lon" becomes a Point, a semicolon-separated list becomes a LineString, and a list whose first and last points match becomes a Polygon.
• _geolocation becomes a GeoJSON Point under geolocation.
• Fields matching Number Mask are converted to numbers; fields matching Multiselect Mask are split on spaces into arrays.

Reference values downstream by expression, for example {{ $json.question_1 }} (raw) or {{ $json.id }} (reformatted).

Usage Examples

• Start a workflow when a new survey response is submitted in KoBoToolbox
• Trigger data processing when field agents submit a form
• Automate notifications when a humanitarian assessment form is completed
• Sync KoBoToolbox submission data to a database or spreadsheet

Example Configuration

Listen for submissions and pass the raw payload through:

{
  "type": "kobotoolbox_trigger",
  "parameters": {
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "triggerOn": "formSubmission"
  }
}

Reformat submissions with the default masks:

{
  "type": "kobotoolbox_trigger",
  "parameters": {
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "triggerOn": "formSubmission",
    "formatOptions": {
      "reformat": true,
      "selectMask": "select_*",
      "numberMask": "n_*, f_*"
    }
  }
}

Apply custom field-name masks:

{
  "type": "kobotoolbox_trigger",
  "parameters": {
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "triggerOn": "formSubmission",
    "formatOptions": {
      "reformat": true,
      "selectMask": "choice_*",
      "numberMask": "num_*, float_*"
    }
  }
}

Request attachments with sequential naming:

{
  "type": "kobotoolbox_trigger",
  "parameters": {
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "triggerOn": "formSubmission",
    "formatOptions": {
      "download": true,
      "binaryNamingScheme": "sequence",
      "dataPropertyAttachmentsPrefixName": "attachment_",
      "version": "download_url"
    }
  }
}

Request a medium-size image variant named after the form question:

{
  "type": "kobotoolbox_trigger",
  "parameters": {
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "triggerOn": "formSubmission",
    "formatOptions": {
      "download": true,
      "binaryNamingScheme": "question",
      "version": "download_medium_url"
    }
  }
}

Trigger Behavior

• Activation: When the workflow is activated, a webhook endpoint is registered with the service.
• Deactivation: The webhook is automatically unregistered when the workflow is deactivated.
• Payload: The incoming webhook payload is parsed and output as workflow items.
• Verification: Supports signature verification where applicable.

Tips

Entry point that fires when KoBoToolbox sends a webhook for new form submissions. Configure the Form ID to specify which form to listen on. The trigger event is “On Form Submission”. Use the Options collection to control data reformatting: enable Reformat to parse GeoJSON coordinates and apply number/multiselect field masks. The Multiselect Mask and Number Mask fields use wildcard patterns (e.g. “select_”, “n_, f_*”) to identify which fields should be treated as arrays or numbers.

Important Notes

• The formId must be the actual UID from KoBoToolbox, not the form name
• Conditional fields in formatOptions (binaryNamingScheme, dataPropertyAttachmentsPrefixName, version) only work when download is set to true
• dataPropertyAttachmentsPrefixName is additionally conditional on binaryNamingScheme being "sequence"
• binaryNamingScheme accepts "sequence" (files named with a sequential index prefix) or "question" (files named after the form question field)
• version controls which image resolution URL is used for attachments: "download_url" (original), "download_small_url", "download_medium_url", or "download_large_url"
• The trigger will only activate on form submissions - no other events are currently supported