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.

---

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:

{{ResponseBinding.PaymentCallback.body.transactionId}}
{{ResponseBinding.PaymentCallback.body.status}}
{{ResponseBinding.PaymentCallback.headers['x-event-id']}}