Set Up a Webhook

To use Webhooks, create a FormSpace FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace.-level Webhook in the web portal, then add and configure a Webhook question in the Form Builder The Form Builder is the tool that form designers use to create forms. In the Form Builder, accessed from the TrueContext Web Portal, form designers can add and edit pages, sections, and questions, as well as attach data destinations and configure the form's settings.. Mobile users can then run Webhook actions and retrieve data from external systems while filling out a form.

Available on the Elite tier:

Contents

• Set Up a Webhook
  • Response Usage
  • Webhook creation overview
  • Create a Webhook — Portal
    • Prerequisites
    • Constraints
    • Steps to Set up a Webhook in the Portal
  • Add a Webhook to a form — Form Builder
    • Prerequisites
    • Constraints
  • Steps to set up a Webhook question
    • GENERAL
    • PROPERTIES
  • Related topics

---

Response Usage

Webhooks can be configured in two ways based on how the response is used. A single webhook can serve both purposes, and both can be used in the same form.

Purpose	Functionality	Typical use	Routing requires user confirmation	Trigger options
Info Webhook	Calls an external system and displays the response as read-only in the webhook question. The technician can see the result but cannot edit it.	AI-generated recommendations, risk scores, compliance flags, site conditions, and other reference data surfaced at the right moment in the form.	Not applicable	Automatic or manual
Routing Webhook	Calls an external system and populates other form fields with the response. The technician must tap a button to trigger the call, then confirm before the values are applied.	Populating fields with fetched data: work order details, asset specs, scored or computed values from an external system or AI service, where the technician confirms the result before it takes effect.	Optional; designer can require users to accept or decline before routing.	Manual only

Webhook creation overview

The following table summarizes the configuration steps and where each is performed.

What	Where
Create a Webhook and link it to an HTTP Connection. Either select an existing HTTP Connection or create a new one as part of this step.	FormSpace — Web Portal
Configure Webhook method, URL path, parameters, headers, and request body.	FormSpace — Web Portal
Test the Webhook request.	FormSpace — Web Portal
Add an HTTP Webhook question to the form and select the Webhook that you created.	Form Builder
Map parameter questions in the form to the Webhook parameters.	Form Builder
Configure the Webhook trigger type and how it handles and formats the response, including the content type and any values to route to other questions in the form.	Form Builder

Create a Webhook — Portal

Webhooks are FormSpace-level objects that define how TrueContext calls an external API — including the endpoint, parameters, and headers. Each Webhook is built on a team-level HTTP connection and can be reused across one or more forms.

Note:Updating Webhook parameters affects all forms that use the Webhook. If you add or rename parameters, users can't submit those forms until you map the new parameters to questions. Removing parameters doesn't block submissions, but review and update Webhook mappings in affected forms. To avoid disrupting production forms, create a new Webhook and update your forms to use it instead of editing the existing Webhook.

Prerequisites

• If creating a new Connection, you need credentials to authenticate to the external system. Check the third-party API documentation for the supported authentication method, and confirm that the credentials have permission to perform all required actions.
• Admin user or user with Can Create FormSpace permissions.
• An Elite subscription.

Constraints

• Webhooks send a single synchronous request and receive a single response in the same session.
• Webhook responses can’t contain binary or executable content.
• Each Webhook requires at least one parameter and supports up to 10.

Steps to Set up a Webhook in the Portal

1. Go to Forms & Integrations > Webhooks > CREATE WEBHOOK > HTTP Webhook.

2. On the Name tab, enter a name for the Webhook and, optionally, a description.

3. On the Connection tab, in Connection Configuration, do one of the following:

   Option	Description
   Select an existing Connection	Choose an HTTP Connection from the dropdown. The base connection URL is shown below the dropdown.
   Create a new Connection	Configure the Connection details, including the name, base connection URL, and authentication scheme.

   Info:For full details on creating a new HTTP Connection, see the HTTP Connection topic.

4. In Request Configuration, configure:

   Setting	Description
   HTTP Method
   URL Path
   Query Parameters
   HTTP Headers	Note:This section isn't intended for secret values. Store API keys, tokens, and sensitive information in the Connection instead, where they are encrypted.

5. For POST, PUT, or PATCH requests, in Request Body, configure:

   Setting	Description
   Body Format	Define the request body: None Raw URL-encoded

6. In Test Request, configure:

   Action	Description
   Enter test values	Note:Webhook requests must include at least one parameter of any type.
   Test in progress	Wait while TrueContext runs the test.

7. Review the test result:

   Result	Description
   Test result	A failed test shows the failure reason: A successful test shows the query and the results:

8. Select Create to save the Webhook.

Add a Webhook to a form — Form Builder

Prerequisites

• A FormSpace-level Webhook

Constraints

• Each form that uses a Webhook must include at least one parameter question A parameter question is any question defined in your form that's also used to provide values to an On-Demand Data Source or a Webhook query., up to a maximum of 10; parameters must come from questions, not static values.
• Webhook questions can’t be used directly as parameters for other Webhooks.
• Webhook questions aren't allowed in repeatable or template-based sections.
• Webhook questions can't be used in Conditional Logic rules, or other form logic such as concatenation.
• Each form can reference up to five unique Webhooks.
• Webhook questions aren't available in Customer Feedback Forms Customer Feedback Forms are browser-based, can be used on any platform, and are available to customers and third parties by means of a URL link. They don’t require an app download or a user login..

Steps to set up a Webhook question

GENERAL

1. Configure:

   Setting	Description
   Question Text	Label that mobile users see for the Webhook question.
   Unique Identifier for Question	Unique name that identifies the Webhook question in the form.
   Data and Control Type	Uses a Free Text-style data type and stores the Webhook response as a text value.
   Restrictions	Controls whether the question is: Required — the form can't be submitted until the Webhook action has run successfully. Use with caution: if connectivity is poor, this can block form completion entirely. Read only — the Webhook question is visible but the user can't interact with it. The action can still run automatically if configured, but the user can't manually trigger it. Hidden on device — the Webhook question isn't visible to the mobile user. The action can still run automatically in the background, but the user has no way to trigger it manually or see the response. Hidden on reports — the Webhook response is excluded from submission reports. The action runs and the response is recorded, but it doesn't appear in the output.

PROPERTIES

2. In Webhook Configuration:

   Setting	Description
   Select Webhook
   Response Usage   Display the answer inline as read-only so users can view the result within the form Route the Webhook response to populate other questions in the form
   Webhook Trigger
   Parameter

3. In Answer Definition:

   Setting	Description
   Response Type
   Answer Content	Info:JMESPath A JSON query language. is a case-sensitive query language for extracting values from JSON Webhook responses. For a complete reference, see the JMESPath documentation.
   Does the Webhook response include Markdown formatting?	Note:If you aren't sure, select No. Enabling this when the response doesn't contain Markdown causes the raw syntax characters to appear in the form.

4. Additionally, for routing Webhooks, in Routing Configuration:

   Setting

   Description

   Extract answers with

   Index Note:Use a number or a range of numbers to extract data from an answer and populate other questions in the form. For example, if the answer is ABCDEFG, use a range of 1 to 3 to extract "ABC", or use the number 6 to extract "F". Regex Note:Use regular expressions to extract capture groups and direct them to the chosen questions in a form. Test each expression and its results on each device to ensure consistent results. JMESPath Note:Use JMESPath expressions to extract values from JSON responses and route them to form questions.

5. Select Save to add the Webhook question to the form.

Related topics

• Introduction to Webhooks
• Question Type: Webhook
• Use a Webhook
• View Webhook Submission Data