---
title: "Webhook Trigger"
description: "Trigger flows via external HTTP POST calls, supporting request parsing and custom responses."
---

# Webhook Trigger

## Trigger Type

`webhook`

## Use Cases
- External system callbacks (payment, messaging, notifications, etc.).
- When third-party request parameters need to be parsed for use in subsequent nodes.

## Trigger Timing / Events
- Accessing the system-generated Webhook URL (only `POST` is supported).
- Optional HTTP Basic Authentication.
- Response strategies differ between synchronous and asynchronous modes:
  - Synchronous mode: The response content is determined by the response node; if no response node is reached, the default is 200/500 based on execution status (success / failed).
  - Asynchronous mode: Returns the `response` configured in the trigger directly.

## Configuration Items
| Field | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| basicAuthentication | false | object | false | No | HTTP Basic Authentication configuration. Fill with `false` if not enabled. |
| basicAuthentication.username | string | - | No | Authentication username (required only when enabled). |
| basicAuthentication.password | string | - | No | Authentication password (required only when enabled). |
| request | object | {} | No | Request parsing configuration. |
| request.headers | object[] | [] | No | Request header parsing configuration (used for variable option display and mapping). |
| request.headers[].key | string | - | Yes | Request header name (e.g., `x-signature`). |
| request.query | object[] | [] | No | Query parameter parsing configuration. |
| request.query[].key | string | - | Yes | Query parameter path (supports nesting, e.g., `order.id`). |
| request.query[].alias | string | - | No | Variable alias (affects display only). |
| request.query[]._var | string | - | No | Internal variable name (automatically generated by the UI, e.g., `query_$0`). |
| request.body | object[] | [] | No | JSON request body parsing configuration (only `application/json` is supported). |
| request.body[].key | string | - | Yes | JSON path (e.g., `data.id`). |
| request.body[].alias | string | - | No | Variable alias (affects display only). |
| request.body[]._var | string | - | No | Internal variable name (automatically generated by the UI, e.g., `body_$0`). |
| response | object | - | No | Response configuration for asynchronous mode; defaults to 200 with an empty body if not configured. |
| response.statusCode | number | 200 | Yes | HTTP status code. |
| response.headers | object[] | [] | No | Array of response headers, elements include `name` and `value`. |
| response.headers[].name | string | - | Yes | Response header name. |
| response.headers[].value | string | - | Yes | Response header value (supports template variables). |
| response.body | object | - | No | Response body (JSON), supports template variables. |

## Example Configuration
```json
{
  "basicAuthentication": {
    "username": "webhook",
    "password": "secret"
  },
  "request": {
    "headers": [
      { "key": "x-signature" }
    ],
    "query": [
      { "key": "event", "alias": "Event", "_var": "query_$0" }
    ],
    "body": [
      { "key": "data.id", "alias": "Order ID", "_var": "body_$0" }
    ]
  },
  "response": {
    "statusCode": 200,
    "headers": [
      { "name": "content-type", "value": "application/json" }
    ],
    "body": {
      "ok": true,
      "id": "{{ $context.body.body_$0 }}"
    }
  }
}
```

## Output Variables
The variable selector for this trigger is a tree array of `{ label, value, children? }`. At runtime, join the `value` segments with `.` and prepend `$context`.

- Exposed roots are created only from the configured request extraction items: `headers`, `query`, and `body`.
- Each child node uses `alias` for display, but the runtime path uses `_var` when present; otherwise it falls back to `key`.
- That means a configured query item may display as `Event` while the actual expression is still `{{$context.query.query_$0}}`.
- Example references for the sample configuration above: `{{$context.query.query_$0}}`, `{{$context.body.body_$0}}`, `{{$context.headers.x-signature}}`.
