Approval Gate Node

The Approval Gate pauses a run until a person — or a system — decides. The event waits at the gate; approve it and the run continues through the Approve output, reject it and it continues through the Reject output. If nobody decides in time, the gate decides for them.

How it works

When an event reaches an Approval Gate the run stops and a pending approval is created with the payload as it arrived. Somebody then decides, in whichever of these ways the gate is set up for:

• From the email — the gate emails up to two people a link with Approve and Reject buttons.
• From the dashboard — the Approvals table at the bottom of the node's page lists every wait; expand one and resolve it with a comment.
• From a resume URL — every wait has a signed URL. Opened in a browser it shows the approval page; called from code (with the gate's secret) it decides over HTTP.

The first decision wins. Once decided, the payload continues downstream with an _approval block describing what happened. Past the timeout, the gate applies its auto action — approve or reject — and the run continues the same way.

A gate hung directly from a webhook holds the whole event, not just its own branch: the delivery to the webhook's URL and the webhook's other branches wait for the decision too. Approve, and they run along with the gate's Approve output. Reject, and only the Reject output runs: nothing is delivered, and the event shows as rejected. A gate further down (after any other node) only holds its own branch — the delivery has already happened, so the event stays delivered either way.

On the canvas the gate appears as an amber node with two output handles, main (approved) and rejected. A paused gate does not wait and does not pass events through: the run stops there, and the skip is recorded in telemetry.

The node page, top to bottom

Everything below is what you see when you open an Approval Gate from the canvas, in the same order.

Decided via

How the decision reaches the gate. This choice changes what the rest of the Config tab shows.

Config tab — Native and Gmail

Subject and body accept the usual {{payload.field}} expressions and filters, plus these meta values:

Config tab — Webhook call

Approval page tab

The public page a reviewer sees when they open the link — from the email, from a message, or from the resume URL in a browser.

Timeout and Auto Action on Timeout

Timeout is how long the gate waits (default 24 hours). When it runs out, the gate applies the Auto Action: Auto-reject (the default, fail-safe) or Auto-approve. The wait shows as Expired in the table, the payload continues through the matching output and _approval.resolvedVia reads timeout.

Who can decide

Require sign-in — off by default. Off, anyone holding the approval link can decide, and the record only says which address the link was sent to — not who actually clicked. On, the page asks them to sign in to HostWebhook first and the record names that user. Turn it on when the link is posted to a shared channel and the decision matters.

Run Test (right panel)

Creates a real test wait with the chosen example payload — it shows up in the Approvals table tagged Test. With Native or Gmail the email really goes out to the notify addresses, with a TEST RUN banner on top; with Webhook call nothing is sent and the wait's URL appears in the Resume URL card. Deciding a test wait resolves it only: nothing downstream runs.

Approvals table

Every wait this gate has created, newest first, with a status filter (Pending, Approved, Rejected, Expired) and a search over the payload and the event id. A pending row has Copy URL — its resume URL — and Resolve. Expand a row to see the payload, the details (event, expiry, who decided and how, comment) and, while it is pending, the Approve and Reject buttons. A comment is required to decide from here. The table updates live as decisions arrive.

What the reviewer sees

Decide by webhook call

With Decided via: Webhook call the gate sends no email: the run pauses until something calls its resume URL over HTTP. The URL comes from {{$resumeUrl("Node name")}} in any node before the gate — send it to your backend with an HTTP Action, or post it to Slack or Discord. Opened in a browser it still shows the approval page; called from code it answers JSON. Whichever arrives first wins.

Where the link can go

The node that carries the link has to run while the gate is waiting. Two shapes do that:

Try it from Postman

GET — what is waiting

curl "<resume url>" \
  -H "Accept: application/json" \
  -H "X-HostWebhook-Approval-Secret: hwa_…"

{
  "status": "pending",
  "eventId": "evt_9987e5f6a7b8c9d0e1f2a3b4",
  "expiresAt": "2025-05-01T13:00:00.000Z",
  "payload": { "orderId": "ord_42", "amount": 250000 },
  "decision": null
}

Once decided, status becomes approved or rejected and decision carries the action, who decided and when. Past the timeout it reads expired.

POST — decide and resume

Send any JSON body you like. The only thing it must carry is the decision; the gate reads two fields and leaves the rest alone:

curl -X POST "<resume url>" \
  -H "X-HostWebhook-Approval-Secret: hwa_…" \
  -H "Content-Type: application/json" \
  -d '{ "action": "reject", "message": "Budget is closed for Q3", "ticket": "T-9" }'

The whole body lands inside payload._approval, under the gate's own fields — so your message and ticket are there for the next nodes, and action, resolvedAt, resolvedVia and the rest are always the gate's, whatever the body says:

{
  "message": "Budget is closed for Q3",
  "ticket": "T-9",
  "action": "reject",
  "resolvedAt": "2025-05-01T12:15:00.000Z",
  "resolvedBy": "webhook",
  "resolvedByEmail": null,
  "resolvedVia": "webhook",
  "comment": null,
  "approvalNodeName": "High-Value Transaction Review"
}

The caller receives the configured Reply to the caller, rendered against that same payload, so {{payload._approval.action}} and {{payload._approval.ticket}} both work there. A POST that does not carry the decision gets this instead, and the wait is untouched:

{
  "error": "decision_missing",
  "field": "action",
  "message": "The body has no "action". Send "approve" or "reject" in it; nothing was resumed."
}

Status codes

What comes out

The payload leaves the gate as it arrived, plus an _approval block. It goes through the Approve output (main port) or the Reject output (rejected port) — never both.

{
  "orderId": "ord_42",
  "amount": 250000,
  "_approval": {
    "action": "approve",
    "resolvedAt": "2025-05-01T12:15:00.000Z",
    "resolvedBy": "Jane Cooper",
    "resolvedByEmail": "jane@example.com",
    "resolvedVia": "manual",
    "comment": "Verified by finance",
    "approvalNodeName": "High-Value Transaction Review"
  }
}

Sending the link yourself

Any node that runs before the gate can use {{$resumeUrl("Node name")}} — the gate's exact name — and it resolves to the URL of the wait that this run is about to create. Put it in a Slack or Discord message, an email of your own, or an HTTP Action to your backend. Whoever opens it sees the approval page; whatever calls it with the secret decides over HTTP. The link exists before the gate is reached: opening it too early shows a "not ready yet" page rather than an error.

API reference

The node's JSON never contains the webhook-call secret; it only says webhookCall.hasSecret. Reveal or regenerate it with the two secret routes below.

curl -X POST /api/approval-nodes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<your-workspace-id>",
    "name": "High-Value Transaction Review",
    "provider": "webhook",
    "webhookCall": { "decisionField": "action", "reply": { "status": 200, "body": { "ok": true } } },
    "timeoutMinutes": 60,
    "autoActionOnTimeout": "reject",
    "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }]
  }'