Approval Gate Node

The Approval Gate holds events for manual review before they continue through the pipeline. Reviewers can approve or reject events via the dashboard or API. Configure timeouts with automatic actions and email notifications to ensure events are never left in limbo.

Overview

When an event reaches an Approval Gate, it is paused with status AWAITING_APPROVAL. The event remains held until a reviewer explicitly approves or rejects it — or until the configured timeout expires, at which point the autoActionOnTimeout is applied. Approved events continue through the pipeline; rejected events are stopped.

Notification emails can be sent to specified addresses when an event enters the approval queue, ensuring reviewers are alerted promptly. On the canvas, Approval Gate nodes appear as amber rectangles.

Configuration

Field	Type	Default	Description
name	string	—	Friendly label for the approval gate
isActive	boolean	true	Whether the approval gate is enabled (when disabled, events pass through)
timeoutMinutes	number	1440	Minutes before automatic action is applied (default: 24 hours)
autoActionOnTimeout	string	reject	'approve' or 'reject' — action taken when timeout expires
notifyEmails	string[]	[]	Email addresses to notify when an event enters the approval queue
inputNodes	{ nodeType, nodeId }[]	[]	Upstream nodes that feed this one. nodeType is the node kind (webhook, scheduledWorkflow, filter, …)

ℹWhen autoActionOnTimeout is set to approve, events that are not manually reviewed within the timeout period will automatically continue through the pipeline. Use reject (the default) for a fail-safe approach where unreviewed events are blocked.

Create an Approval Gate

bashCreate Approval Gate

curl -X POST /api/approval-nodes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Transaction Review",
    "isActive": true,
    "timeoutMinutes": 60,
    "autoActionOnTimeout": "reject",
    "notifyEmails": [
      "[email protected]",
      "[email protected]"
    ],
    "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }]
  }'

Response

json201 Created

{
  "_id": "6656b4c5d6e7f8a9b0c1d2e3",
  "name": "High-Value Transaction Review",
  "isActive": true,
  "timeoutMinutes": 60,
  "autoActionOnTimeout": "reject",
  "notifyEmails": [
    "[email protected]",
    "[email protected]"
  ],
  "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
  "ownerId": "org_abc123",
  "createdAt": "2025-05-01T12:00:00.000Z",
  "updatedAt": "2025-05-01T12:00:00.000Z"
}

Update an Approval Gate

bashUpdate Approval Gate

curl -X PATCH /api/approval-nodes/6656b4c5d6e7f8a9b0c1d2e3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "timeoutMinutes": 120,
    "autoActionOnTimeout": "approve",
    "notifyEmails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'

Approve or Reject Events

Use the dedicated approve/reject webhooks to take action on pending events. These can be called from the dashboard UI or programmatically via the API.

Approve an event

bashApprove

curl -X POST /api/approval-nodes/6656b4c5d6e7f8a9b0c1d2e3/approve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_9987e5f6a7b8c9d0e1f2a3b4",
    "reason": "Verified by finance team"
  }'

Reject an event

bashReject

curl -X POST /api/approval-nodes/6656b4c5d6e7f8a9b0c1d2e3/reject \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_9987e5f6a7b8c9d0e1f2a3b4",
    "reason": "Suspicious transaction flagged by security"
  }'

⚠Approval and rejection are irreversible. Once an event is rejected, it cannot be approved later. If you need to re-process a rejected event, you must replay it from the source.

Canvas Integration

The Approval Gate uses canvas type approval-node and renders in amber. It sits inline in the pipeline and blocks events until they are manually approved or the timeout expires.

jsonCanvas node data

{
  "id": "approval-6656b4c5d6e7f8a9b0c1d2e3",
  "type": "approval-node",
  "position": { "x": 500, "y": 200 },
  "data": {
    "label": "High-Value Transaction Review",
    "approvalNodeId": "6656b4c5d6e7f8a9b0c1d2e3",
    "timeoutMinutes": 60,
    "autoActionOnTimeout": "reject",
    "pendingCount": 3,
    "isActive": true
  }
}

Payload Examples

Event entering approval queue

jsonEvent status: AWAITING_APPROVAL

{
  "_id": "evt_9987e5f6a7b8c9d0e1f2a3b4",
  "webhookId": "6654a1b2c3d4e5f6a7b8c9d0",
  "status": "AWAITING_APPROVAL",
  "payload": {
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "amount": 250000,
        "currency": "usd",
        "customer": "cus_vip789"
      }
    }
  },
  "approvalNodeId": "6656b4c5d6e7f8a9b0c1d2e3",
  "approvalDeadline": "2025-05-01T13:00:00.000Z",
  "createdAt": "2025-05-01T12:00:00.000Z"
}

Event after approval

jsonEvent approved

{
  "_id": "evt_9987e5f6a7b8c9d0e1f2a3b4",
  "status": "pending",
  "approvalResult": {
    "action": "approved",
    "reason": "Verified by finance team",
    "decidedAt": "2025-05-01T12:15:00.000Z",
    "decidedBy": "user_admin123"
  }
}

Event after rejection

jsonEvent rejected

{
  "_id": "evt_9987e5f6a7b8c9d0e1f2a3b4",
  "status": "REJECTED",
  "approvalResult": {
    "action": "rejected",
    "reason": "Suspicious transaction flagged by security",
    "decidedAt": "2025-05-01T12:20:00.000Z",
    "decidedBy": "user_security456"
  }
}

Notification email payload

jsonEmail notification

{
  "to": ["[email protected]", "[email protected]"],
  "subject": "Approval Required: High-Value Transaction Review",
  "body": {
    "approvalNodeName": "High-Value Transaction Review",
    "eventId": "evt_9987e5f6a7b8c9d0e1f2a3b4",
    "payloadPreview": {
      "type": "payment_intent.succeeded",
      "amount": 250000,
      "currency": "usd"
    },
    "deadline": "2025-05-01T13:00:00.000Z",
    "approveUrl": "https://app.hostwebhook.com/approvals/evt_9987e5f6a7b8c9d0e1f2a3b4",
    "autoAction": "reject"
  }
}

Use Cases

High-value transaction review — Require manual approval for payments exceeding a threshold before processing the order.
Security review — Hold suspicious events (flagged by a Filter node) for security team review before allowing them through.
Compliance gates — Enforce regulatory review steps for financial or healthcare-related events.
Deployment approvals — Hold CI/CD deployment triggers for manual sign-off before proceeding.
Content moderation — Review user-generated content events before forwarding to publishing services.

API Reference

Method	Webhook	Description
GET	/api/approval-nodes	List all approval gate nodes
POST	/api/approval-nodes	Create a new approval gate
GET	/api/approval-nodes/:id	Get a specific approval gate
PATCH	/api/approval-nodes/:id	Update an approval gate
DELETE	/api/approval-nodes/:id	Delete an approval gate
POST	/api/approval-nodes/:id/approve	Approve a pending event
POST	/api/approval-nodes/:id/reject	Reject a pending event

✦Combine an Approval Gate with a Filter node to only require manual review for specific events. For example, use a Filter to catch transactions over $1,000 and route them through the Approval Gate while smaller transactions pass through automatically.

ℹThe approval/reject actions are also available in the dashboard UI. Click on a pending event to view its payload and approve or reject it with one click.