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

# Webhook Trigger & Callback Node

> Listen for external asynchronous events, verify cryptographic HMAC signatures, and resume suspended workflows.

The **Webhook Node** (`component-webhook`) enables asynchronous external systems to trigger workflows or resume suspended flows when long-running operations finish.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Flow as Quixa Workflow
    participant Gateway as External Payment Gateway
    participant Webhook as Quixa Webhook Listener

    Flow->>Gateway: POST /v1/charges (Initiate 3D Secure)
    Gateway-->>Flow: 202 Accepted (Wait for callback)
    Note over Flow: Flow pauses at Webhook Wait Node
    Gateway-->>Webhook: POST /webhooks/callback/{token} (Charge Authorized)
    Webhook->>Flow: Verify HMAC & Resume execution
    Flow->>Flow: POST /v1/fulfillment (Dispatch Order)
```

***

## 1. Operating Modes

### Mode 1: Workflow Entry Trigger

Acts as the first node in a flow. External services (e.g., GitHub, Stripe, internal event buses) POST JSON payloads to a dedicated Quixa webhook endpoint to trigger automated workflow execution.

### Mode 2: In-Flow Callback Listener (Wait for Event)

Acts as an intermediate pause gate within an active flow:

1. Upstream node initiates an asynchronous job (e.g., payment authorization, background file transcoding).
2. The flow generates a unique callback token and pauses at the **Webhook Wait Node**.
3. When the third-party provider posts the result to the callback URL, Quixa verifies the payload and **resumes the flow immediately from that step**.

***

## 2. Security & HMAC Verification

To protect against spoofing, Quixa provides built-in cryptographic signature verification:

* **Signature Header**: Specify the expected header name (e.g., `X-Hub-Signature-256`, `Stripe-Signature`).
* **Secret Key**: Stored securely as an environment variable (`{{env.webhookSecret}}`).
* **Algorithm**: `HMAC-SHA256`, `HMAC-SHA1`, or custom pre-script verification.
* **Timestamp Tolerance**: Enforces maximum age (e.g., 300 seconds) to prevent replay attacks.

***

## 3. Configuration Properties

| Property | Default | Description |
| :- | :- | :- |
| **Endpoint Path** | Auto-generated | The unique public or VPC endpoint path for this webhook. |
| **Timeout (Minutes)** | `15` | Maximum duration the flow will wait for the callback before timing out. |
| **Verification Method** | `None` | `None`, `HMAC-SHA256`, `Bearer Token`, or `Custom Header`. |
| **Payload Schema** | `Optional` | JSON schema for validating incoming callback payloads. |

***

## 4. Consuming Webhook Payloads Downstream

Once received, the callback payload is fully accessible to subsequent nodes via **Response Binding**:

```handlebars theme={null}
{{ResponseBinding.PaymentCallback.body.transactionId}}
{{ResponseBinding.PaymentCallback.body.status}}
{{ResponseBinding.PaymentCallback.headers['x-event-id']}}
```


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