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

# Webhook

> Trigger a flow instantly when an external system sends a request to Zygo

The **Webhook** node gives your flow a unique URL that external systems can call to trigger execution. When a request hits the webhook URL, the flow starts immediately with the incoming data as its input.

## When to Use It

* Receiving events from third-party services (Stripe, GitHub, Shopify, etc.)
* Building an API endpoint powered by your flow
* Connecting Zygo to Zapier, Make, or other automation platforms
* Processing incoming data in real time

## How It Works

**1. Add a Webhook node**

Drag a Webhook node onto your canvas. It should be the first node in your flow (no incoming connections).

**2. Copy the URL**

Each Webhook node gets a unique URL based on its node ID:

```
https://your-zygo-instance.com/api/webhook/{node_id}
```

**3. Configure the external system**

Point your external service at the webhook URL. When it sends a request, your flow triggers.

**4. Publish the flow**

The webhook only accepts requests when the flow is **published**. Unpublished flows return a `403`.

## Configuration

> [accordion] Allowed Method
>
> Restrict which HTTP method the webhook accepts.
>
> | Option | Behavior |
> | - | - |
> | **POST** (default) | Only accepts POST requests |
> | **GET** | Only accepts GET requests |
> | **PUT** | Only accepts PUT requests |
> | **DELETE** | Only accepts DELETE requests |
> | **PATCH** | Only accepts PATCH requests |
> | **ANY** | Accepts all HTTP methods |
>
> Requests using a non-allowed method receive a `405 Method Not Allowed`.

> [accordion] Authentication
>
> Protect your webhook with an `Authorization` header check. Set the expected value, and Zygo will reject any request that doesn't match.
>
> ```
> Bearer my-secret-token-123
> ```
>
> You can also reference a credential:
>
> ```
> Bearer {{credential.webhook_secret}}
> ```
>
> Unauthenticated requests receive a `401 Unauthorized`.

> [accordion] Response Status
>
> The HTTP status code returned to the caller after the webhook is received. Defaults to `200`.
>
> Common values: `200` (OK), `201` (Created), `202` (Accepted).

> [accordion] Response Body
>
> The JSON body returned to the caller. Defaults to:
>
> ```json theme={null}
> {"ok": true}
> ```
>
> Customize this to return whatever the calling system expects.

## Input Data

The Webhook node captures everything about the incoming request and makes it available to downstream nodes:

| Field | Description |
| - | - |
| `method` | The HTTP method used (GET, POST, etc.) |
| `path` | The webhook node ID |
| `headers` | All request headers as key-value pairs |
| `query` | URL query parameters as key-value pairs |
| `body` | The request body, parsed as JSON |

Reference these in downstream nodes:

```
Payload name: {{1_Webhook.body.name}}
API key header: {{1_Webhook.headers.X-Api-Key}}
Query param: {{1_Webhook.query.action}}
```

## Important Notes

> [!WARNING]
>
> The webhook responds to the caller **immediately** with the configured response. The flow then executes asynchronously in the background. If you need to return the flow's result to the caller, consider using a different pattern (e.g., the caller polls a status endpoint).

> [!NOTE]
>
> The webhook URL is the node's database ID — not a secret token. If you need to prevent unauthorized access, always configure an **Authentication** header.

## Testing Your Webhook

You can test your webhook locally using curl:

```bash theme={null}
# Simple POST
curl -X POST https://your-zygo-instance.com/api/webhook/{node_id} \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"name": "Jane"}}'

# With authentication
curl -X POST https://your-zygo-instance.com/api/webhook/{node_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token-123" \
  -d '{"event": "order.created", "order_id": "12345"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.