Webhook Trigger Deep Dive — Variable Configuration, API Security & Integration Patterns

The Webhook Trigger brings event-driven automation to ApudFlow. Instead of running on a fixed schedule, your workflow fires the moment an external system calls the endpoint. This guide covers everything you need to know to use it effectively.

Video Tutorial

How the Webhook Trigger Works

The Webhook Trigger is a passive node — it sits in your workflow and waits for an HTTP call. When you click Run Test, it:

1. Saves the variable definitions to a persistent configuration in the database
2. Generates (or reuses) a stable webhook ID from the node ID
3. Returns the endpoint URL: /api/t/{workflow_id}/{webhook_id}

From that moment on, any POST or GET request to that URL triggers a new workflow run with the provided variables injected into the context.

Endpoint Isolation

The webhook trigger lives under /api/t/ — a dedicated path prefix that is completely separate from the data provider endpoints under /api/w/. There is no route overlap, so both features coexist without interference.

Variable Configuration (Visual Editor)

When you click a Webhook Trigger node on the canvas, the right panel shows a custom visual variable editor. Here is how each field works:

Name

The key that callers use when sending values. For example, if you name a variable symbol, callers send {"symbol": "BTCUSD"} and {{symbol}} resolves to BTCUSD anywhere downstream.

Type

Type	Behavior	Example Value
string	Free text, no conversion	"BTCUSD"
integer	Coerced to number; rejects non-numeric	100
boolean	Coerced from "true"/"1"/"yes"	true
list	Must match one of the defined choices	"buy"

Default Value

Used when the caller does not supply this variable. For booleans, the editor shows a dropdown instead of a text field. For integers, it shows a number input.

Required Toggle

If toggled on, the endpoint returns a 400 Bad Request when the variable is missing. Use this for values your workflow absolutely needs to function.

Choices (List Type Only)

When you pick the list type, a textarea appears. Type one option per line:

buy
sell
hold

The endpoint validates that incoming values match one of these exactly.

Optional API Key Authentication

By default, the webhook endpoint is open — anyone with the URL can trigger your workflow. If you want to restrict access, set an API Key in the trigger configuration (visible in the Advanced section of the right panel).

When an API key is configured, callers must authenticate:

Via header (recommended):

Authorization: Bearer your-secret-api-key

Via query parameter (GET requests):

/api/t/{workflow_id}/{webhook_id}?api_key=your-secret-api-key&symbol=BTCUSD

If the key doesn't match, the endpoint returns 401 Unauthorized with a descriptive error message. The api_key query parameter is automatically excluded from the workflow variables — it never reaches downstream nodes.

Integration Patterns

Pattern 1: External Trading System

A trading bot running on a VPS detects a breakout and calls your workflow to execute the rest of the strategy.

[Python Bot] ──HTTP POST──→ [Webhook Trigger] ──→ [Validate Signal]
                                                    ↓
                                            [Fetch Market Data]
                                                    ↓
                                            [AI Analyzer]
                                                    ↓
                                            [Execute / Alert]

Bot code (Python):

import requests

webhook_url = "https://api.apudflow.io/api/t/wf_abc123/6vnkt"
payload = {
    "symbol": "BTCUSD",
    "direction": "long",
    "entry_price": 67500,
    "stop_loss": 67000,
    "take_profit": 69000,
}
headers = {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json",
}
resp = requests.post(webhook_url, json=payload, headers=headers)
print(resp.json())  # {"status": "ok", "run_id": "...", ...}

Pattern 2: GitHub Webhook → Workflow

A GitHub Actions pipeline calls the webhook after a successful deploy.

[GitHub Actions] ──HTTP POST──→ [Webhook Trigger] ──→ [Run Tests]
                                                       ↓
                                               [Send Slack Notification]
                                                       ↓
                                               [Update Dashboard]

GitHub Actions step:

- name: Trigger ApudFlow workflow
  run: |
    curl -X POST "${{ secrets.APUD_WEBHOOK_URL }}" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${{ secrets.APUD_API_KEY }}" \
      -d '{
        "version": "${{ github.sha }}",
        "environment": "production",
        "deployed_by": "${{ github.actor }}"
      }'

Pattern 3: Worker-to-Workflow Chaining

One workflow's final output triggers a second, independent workflow. This keeps each workflow focused and testable.

[Workflow A: Data Collection]
        ↓
[AI Classifier] → categorizes signal
        ↓
[HTTP Post Node] → calls Workflow B's webhook
        ↓
[Workflow B: Execution]
        ↓
[Execute Trade] → [Log to User Lists]

The HTTP Post can be done using the External Data Provider worker in "push" mode, or by using a custom HTTP request node if available.

Pattern 4: Scheduled + Webhook Hybrid

Some runs happen on schedule (e.g. every hour for market data), others are triggered by events. Both the Schedule Trigger and Webhook Trigger can feed into the same downstream pipeline.

graph LR
    S[Schedule Trigger - hourly] --> W[Validate & Process]
    H[Webhook Trigger] --> W
    W --> I[Indicators]
    I --> G[Signal Generator]
    G --> LG[Log Results]

The downstream nodes don't care which trigger started them — {{contextVars}} contain whatever data each trigger provided.

Testing Your Webhook

Quick Test With curl

# POST with JSON body
curl -X POST "https://api-t.apudflow.io/api/t/YOUR_WORKFLOW_ID/YOUR_WEBHOOK_ID" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTCUSD", "limit": 100}'

# GET with query params
curl "https://api-t.apudflow.io/api/t/YOUR_WORKFLOW_ID/YOUR_WEBHOOK_ID?symbol=BTCUSD&limit=100"

Expected Response

{
  "status": "ok",
  "run_id": "6a36c63646a79d5f58ea4a4c",
  "workflowId": "YOUR_WORKFLOW_ID",
  "webhookId": "YOUR_WEBHOOK_ID",
  "runSequence": 7,
  "message": "Workflow triggered successfully",
  "variables": {
    "symbol": "BTCUSD",
    "limit": 100
  },
  "symbol": "BTCUSD",
  "limit": 100
}

Note that each variable also appears as a top-level field ("symbol": "BTCUSD") so you can see values at a glance without expanding the variables object.

Error Handling

HTTP Status	Meaning	Likely Cause
200	Run created successfully	Normal operation
400	Bad request	Missing required variable, or list value not in choices
401	Unauthorized	API key is required but missing or wrong
404	Not found	Webhook trigger not configured (run the trigger first)
500	Internal error	Database or queue issue — check server logs

Limitations

• The endpoint URL is stable for a given workflow + node — re-running the trigger with the same node ID produces the same webhook ID
• Variables are limited to the types described above (string, integer, boolean, list) — for complex nested objects, flatten them into multiple variables
• The endpoint does not support file uploads or binary data at this time

Tips for Production Use

1. Always set an API key if the endpoint is publicly accessible
2. Use descriptive variable names — they become the keys in contextVars and are used in {{variable}} syntax
3. Validate webhook calls in your workflow — add a condition or AI check after the trigger to inspect the data
4. Log incoming calls — connect a User Lists or database worker after the trigger to record all invocations
5. Monitor run sequences — the runSequence field in the response helps you track call ordering

Related Resources

• External Data Provider — Webhook Endpoints
• Trigger Workers Overview
• Workflows Overview