The Webhook integration provides a unique endpoint (URL) to which you can send HTTP requests (often triggered by events) in real time. This allows external services to notify your system of specific events, triggering workflows in Torq.

About Webhooks

A webhook enables one application to send real-time data or notifications to another application. It works as an automated, user-defined HTTP callback that is triggered by specific events in the source application.

For instance, when an event occurs (e.g., user activity, a malicious file detection, or a new email), the webhook sends a message (usually an HTTP POST request) with data about the event to a specified URL (the endpoint Torq provides).

Key Features of Webhooks:

Event-Driven: Triggered only when a specific event happens, making them more efficient than polling.
Real-Time: Sends data immediately after an event, providing near-instant updates.
Customizable: Users define the events and provide the receiving URL.

Torq's trigger webhook supports the following requests:

POST: Sends data to create or update a resource.
GET: Retrieves data without modifying resources.
OPTIONS: Requests information about available communication options for a resource.

Recognized Content Types

Torq webhooks support multiple content types, which are converted into JSON format. You can access the event data as key-value pairs within the JSON.

application/JSON
application
text
application/x-www-form-URL-encoded

Raw Mode

You can configure webhooks to accept raw HTTP requests by selecting the Accept raw HTTP requests checkbox when creating or editing a webhook integration. In raw mode, the webhook handles unrecognized content types and accesses the raw HTTP request, including headers like X-Real-IP (for the public source IP), content-type, the user-agent, and any custom headers.

In raw mode, unrecognized requests place event data in string format within $.event.body. You can then extract data, such as IP or email addresses, using an extraction utility step with $.event.body as input.

Example of a trigger event in raw mode:

{
  "body": {
    "hello": "world"
  },
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Authorization": [
      "bearer ***nskjaNjsnsjs"
    ],
    "Content-Length": [
      "20"
    ],
    "Content-Type": [
      "application/x-www-form-urlencoded"
    ],
    "User-Agent": [
      "curl/8.1.2"
    ],
    "X-Real-Ip": [
      "77.137.**.182"
    ]
  },
  "http_method": "POST"
}

Trigger Torq Workflows via a Webhook

Step One: Create a Webhook Integration in Torq

Navigate to Integration: Go to Build > Integrations > Triggers > Webhook and click Add.
Name the Integration: Provide a meaningful name for the integration - this cannot be changed later.
(Optionally) Enable Raw HTTP: By default, the integration will work only with recognized content types. To work with unrecognized content types, check the Accept raw HTTP requests checkbox.
(Optionally) Add Authentication: If needed, add authentication headers. Doing so is recommended to enhance security.
Finalize: Click Add to save the integration.

Step Two: Trigger Your Workflow via the Webhook URL

Once the webhook trigger integration is created and subsequently associated with a workflow, the workflow can be triggered in several ways:
- User-facing:
  - Send the webhook URL via a Torq Interact form or combine several webhook URLs into one Torq Interact form to allow triggering multiple workflows.
  - Embed the webhook as a hyperlink in service tickets.
  - Embed the webhook in a message (Slack, Teams, etc.) for the receiver to click and trigger the Torq workflow.
- Third-party:
  - Enter the webhook in a third-party application, which will send HTTP post requests in near real-time when a specific event occurs.
- Manual:
  - The webhook can be entered directly into a browser to trigger the workflow.

Step Three: Create a Torq Workflow

Create a New Workflow: Navigate to Build > Workflows > Create a Workflow > New Blank Workflow.
Name the Workflow: Give the workflow a unique and meaningful name.
Pick a Trigger: Under Pick your trigger, click Integrations.
Pick your Integration: Click Pick your integration and search for Webhook.
1. Click the Webhook square.
2. Locate the trigger you made earlier and click it.
Build: The new workflow will be created and available for you to add steps and logic.

Optionally: Add Conditions to Your Webhook Trigger

You can add conditions to the trigger so that the workflow will only run when the webhook event meets certain conditions.
If you enabled Raw Mode when creating or editing the webhook integration, you can add conditions to the trigger by clicking on the trigger and clicking Add Condition.
For example, you can add the condition {{ $.event.headers.'X-Real-Ip'}} does not equal 8.8.8.8 to ensure that the workflow will not run when triggered by certain IP addresses.

Optionally: Customize your Endpoint

You can append key-value pairs to the URL when sending or saving it. These pairs will then be passed into the trigger event JSON.
For example, you can add key-value pairs to the webhook URL like this:
https://hooks.torq.io/v1/webhooks/997f45e6- - - -ac483691e340?key1=value1&key2=value2&key3=value3
The key-value pairs will be available in the trigger event JSON and can be referenced during the workflow run using the context menu {{$.}}.