> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Trigger Tracecat workflows from external systems with webhooks: configure secret URLs, parse JSON or form payloads, and validate inbound requests.

## Overview

Webhooks start a workflow from an external system. The URL includes the webhook secret. `POST` is the primary method. `GET` also works for verification flows. The workflow must be published before the webhook runs.

<img src="https://mintcdn.com/tracecat/9IEnC4OWdnuB3EvN/img/triggers/webhook.png?fit=max&auto=format&n=9IEnC4OWdnuB3EvN&q=85&s=7137b41425fd10e8b896349010276ec0" alt="Webhook trigger" width="2874" height="1764" data-path="img/triggers/webhook.png" />

## Using webhook payloads

The request body becomes `TRIGGER`, for example `${{ TRIGGER.alert_id }}`.

## Supported request formats

Parsing:

* Empty body: no trigger payload is created.
* JSON by default: the body is parsed as JSON and becomes `TRIGGER`.
* Form payloads with `application/x-www-form-urlencoded`: the body is parsed as a dictionary. Form field names become keys on `TRIGGER`.
* NDJSON payloads with `application/x-ndjson`, `application/jsonlines`, and `application/jsonl`: Tracecat starts one workflow run per JSON line. `TRIGGER` is that line, not the full request body.

## Securing webhooks

### Allowed HTTP methods

Allowed methods can be `GET`, `POST`, or both. Requests that use a method outside the allowed list are rejected.

### API key authentication

Webhook API keys are optional. If configured, the sender must include `x-tracecat-api-key`. The UI supports generate, rotate, revoke, and delete. A revoked key blocks requests until a new key is generated or API key protection is removed.

### IP allowlist

Requests can be restricted to specific IPs or CIDR ranges. The allowlist is IPv4-only.

## Response

Default response:

```json theme={null}
{
  "message": "Workflow execution created",
  "wf_id": "wf_3mYp8JkL2nQr7sTu9vWx0Z",
  "wf_exec_id": "wf_3mYp8JkL2nQr7sTu9vWx0Z/exec_7aBcDeFgHiJkLmNoPqRsTu"
}
```

Query parameters:

* `echo=true`: add the original request body to the response under `payload`.
* `empty_echo=true`: return an empty `200` with no body. Implies `echo=true`.
* `vendor=okta`: handle Okta verification challenges. See [Okta verification](#okta-verification).

## Synchronous execution with /wait

To run a workflow synchronously and receive its `return` value in the response, use the `/wait` endpoint described in [Workflows-as-APIs](/automations/triggers/workflows-as-apis).

## Slack event subscriptions

Slack event subscription verification uses `?echo=true`.

## Slack modal close and fast acknowledgements

Slack interactive flows that need a fast empty acknowledgement use `?echo=true&empty_echo=true`.

## Okta verification

Okta verification requests use `vendor=okta`. Tracecat reads `x-okta-verification-challenge` and returns:

```json theme={null}
{
  "verification": "<challenge>"
}
```