Webhook

The Webhook node fires an outbound HTTP call with an HMAC-signed body and then picks the next port based on a named field in the response. Unlike the API node — which has a fixed success / fail fork — Webhook lets the receiver tell the recipe which branch to take next.

Configuring the node

1. Drop the Webhook node from the Integration category onto the canvas.
2. Open the configuration drawer:
   • Method — usually POST (default).
   • URL — the receiver endpoint. Supports {{scope.variable}} interpolation.
   • Headers — key/value rows.
   • Body (JSON) — the payload. Variable interpolation is applied.
   • Credential name — pulls an entry from the Credential vault to set the auth headers.
   • Timeout — 5 s, 10 s, or 30 s.
   • Retry once on 5xx / timeout (+2s) — same retry policy as the API node.
   • Signature secret — shared secret used to compute an HMAC-SHA-256 of the request body. The runtime adds the result as the X-CraftBot-Signature-256: sha256=… header so the receiver can verify the request originated from CraftBot.
   • Response discriminator path — dot-path on the JSON response whose string value picks the outcome port (default: outcome). For example, with the default and a receiver that replies {"outcome": "ticket_created"}, the recipe advances down the ticket_created port.

Output ports

• fail — non-2xx response, network error, or timeout. The variables $webhook.lastStatus, $webhook.lastBody, and $webhook.lastLatencyMs are written.
• fallback — 2xx response but the discriminator field didn’t match any configured port.
• <discriminator-value> — one named port per outcome you want to handle. Add the port name on the canvas (drag a connector off the node); the receiver’s value for the discriminator field must match the port name exactly.

Response mapping (configured outside the drawer today)

Like the API node, the Webhook runtime supports mapping JSON response fields onto recipe variables. The editor isn’t wired into the drawer yet — tracking fix in POSTPONED_FIXES.md PF-9 .

When to use it

• Receiver-driven routing — your CRM decides whether to follow up with “ticket created”, “duplicate”, “needs human review”, or another outcome, and your recipe handles each differently.
• Signed events fanning out to your data warehouse, audit pipeline, or internal services that require HMAC verification.

When not to use it

• A fixed 2xx / non-2xx fork is all you need — use API instead.
• You don’t care about the response and just want to log an event — still use Webhook, but leave the discriminator path on its default and route all 2xx traffic down a single named port.

Notes

• The signature header is only added when both a signature secret and a non-empty body are present.
• The discriminator value is matched case-sensitively against the port names you added on the canvas. If the receiver replies with an outcome no port handles, the runtime falls back to the fallback port; if that port is also unwired, the session escalates.
• Async-mode webhooks (recipe parks while the receiver calls CraftBot back) are not yet supported — the drawer surfaces the limitation. Use the Agent node when you need an async callback shape.