Guides | Ventryx Docs

Building a workflow automation

Workflows define sequences of automated steps triggered by events. Here's how to build one end-to-end:

1. Define your workflow

curl — Create workflow

curl -X POST https://api.ventryx.io/v1/workflows \
  -H "Authorization: Bearer vtx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New order notification",
    "trigger": {
      "event": "order.created"
    },
    "steps": [
      {
        "type": "send_notification",
        "channel": "email",
        "template": "order_confirmation"
      }
    ]
  }'

2. Emit the trigger event

When a new order is placed in your system, emit the corresponding event to activate the workflow:

curl — Emit event

curl -X POST https://api.ventryx.io/v1/events \
  -H "Authorization: Bearer vtx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "data": {
      "order_id": "ord_98765",
      "customer_email": "[email protected]",
      "total": 149.99
    }
  }'

3. Monitor execution

Check the workflow run status via the dashboard or by polling GET /workflows/:id/runs.

Setting up an approval flow

Approval flows gate actions on explicit human sign-off before proceeding. Use them for expense approvals, contract reviews, or access requests.

1. Create the approval workflow

curl

curl -X POST https://api.ventryx.io/v1/workflows \
  -H "Authorization: Bearer vtx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Expense approval",
    "trigger": { "event": "expense.submitted" },
    "steps": [
      {
        "type": "require_approval",
        "approvers": ["[email protected]"],
        "timeout_hours": 48
      },
      {
        "type": "send_notification",
        "channel": "email",
        "template": "expense_approved"
      }
    ]
  }'

2. Handle approval outcomes

Set up a webhook to receive the approval.completed event and act on the decision field (approved or rejected).

Receiving webhooks

Ventryx can push event notifications to your server via webhooks instead of requiring you to poll the API.

1. Register your endpoint

curl

curl -X POST https://api.ventryx.io/v1/webhooks \
  -H "Authorization: Bearer vtx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ventryx",
    "events": ["workflow.completed", "approval.completed"]
  }'

2. Verify signatures

Every webhook request includes a Ventryx-Signature header. Verify it using your webhook secret to prevent spoofed requests:

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}