Webhook triggers

A webhook is the inbound counterpart to the rest of the platform: where the authenticated POST /api/workflows/{id}/runs endpoint lets you start runs, a webhook lets an external system start them without holding a workspace API key. You enable it, hand the resulting URL to the sender, and every POST to that URL creates a run that flows through the same engine — graph validation, quota, checkpoints, gates, retries, and audit included.

Enable, rotate, and disable

A workflow's webhook is controlled by three endpoints under the workflow itself. Enabling mints a fresh secret; the returned url embeds it and is the only place the full URL is shown assembled for you.

{
  "enabled": true,
  "url": "http://localhost:8000/api/hooks/9bc62f209c52/f3a1c09be2d44d1808b7a5c6e2f09a41"
}

{
  "enabled": true,
  "url": "http://localhost:8000/api/hooks/9bc62f209c52/f3a1c09be2d4…",
  "require_signature": false,
  "timestamp_tolerance_seconds": 300,
  "dedup_window_seconds": 0,
  "event_id_field": "event_id"
}

The inbound trigger endpoint

The URL has the shape /api/hooks/{workflow_id}/{secret}. It is deliberately exempt from session and API-key auth so third-party systems can call it directly — the secret path segment is the entire credential.

$ curl -X POST "http://localhost:8000/api/hooks/9bc62f209c52/f3a1c09be2d44d1808b7a5c6e2f09a41" \
    -H "content-type: application/json" \
    -d '{"ticket": "I was double charged", "customer_id": "cus_412"}'

HTTP/1.1 201 Created
{ "run_id": "af772b3602ef", "status": "pending" }

How the body becomes input

• A JSON object body becomes the run input directly — templates and expressions read its keys as {ticket}, {customer_id}, and so on, just like a manual run's input
• A non-object body (array, string, number) is wrapped as {"payload": ...} so state always has a predictable shape
• An empty body is accepted and treated as {}; a body that is present but not valid JSON is rejected with 400
• The response is 201 with { "run_id", "status": "pending" } — poll GET /api/runs/{run_id} or subscribe to its event stream to follow progress

Signing, replay protection & de-duplication

The URL secret is enough on its own, but for anything that touches money or state you can turn on three additional, opt-in controls per workflow — so a leaked URL is no longer sufficient, a captured request cannot be replayed, and a sender that retries never double-acts.

HMAC signatures & timestamps

With require_signature on, each delivery must send two headers. The signature is computed over "{timestamp}." + raw_body — the timestamp is inside the signed material, so a captured signature cannot be replayed with a fresh time:

• X-Ballast-Timestamp — unix seconds; rejected 401 if outside timestamp_tolerance_seconds
• X-Ballast-Signature — sha256=<hex>, an HMAC-SHA256 over "{timestamp}." + raw_body keyed by the webhook secret, compared in constant time

import hmac, hashlib, time, json, requests

secret = "f3a1c09be2d4…"                       # the webhook secret from the URL
body   = json.dumps({"event_id": "evt_912", "amount": 4200}).encode()
ts     = str(int(time.time()))
sig    = "sha256=" + hmac.new(secret.encode(), f"{ts}.".encode() + body,
                              hashlib.sha256).hexdigest()

requests.post(url, data=body, headers={
    "content-type": "application/json",
    "X-Ballast-Timestamp": ts,
    "X-Ballast-Signature": sig,
})

Ingest de-duplication

Set dedup_window_seconds above zero and Ballast keys each delivery by its event id (the X-Ballast-Event-Id header, else the configured event_id_field, else a body id). A duplicate delivery of the same event within the window returns the original run instead of creating a new one, and concurrent duplicate deliveries collapse to a single run (a unique constraint on workflow + event id admits exactly one). This makes the unauthenticated endpoint safe for at-least-once senders — no exactly-once handshake required.

HTTP/1.1 201 Created
{ "run_id": "af772b3602ef", "status": "duplicate", "deduplicated": true }

Security model

Whether or not signing is on, the secret path segment is verified first, and verification is written to leak as little as possible:

• The submitted secret is compared with hmac.compare_digest — a constant-time comparison, so response timing does not reveal how many leading characters were correct
• A wrong workflow id, a workflow with no webhook enabled, and a wrong secret all return the identical 404 Not found — a caller cannot tell which of the two path segments was wrong, so valid workflow ids are not enumerable through this endpoint
• With signing enabled, a missing, malformed, or expired signature is a 401 — distinct from the 404 above so an authorized sender can tell a signing mistake from a wrong URL
• Every enable, rotate, disable, and config change is written to the audit log (webhook_enable, webhook_rotate, webhook_disable, webhook_config), and each triggered run is logged as webhook_run

What a valid request goes through

A correct id and secret is only the first gate. Before a run is created, the request passes the same checks a manual trigger does:

Response codes at a glance

Example: Stripe-style event routing

Point a payment provider's event destination at the webhook URL and let the workflow branch on the delivered payload with a condition node:

# event payload posted by the provider:
# {"type": "charge.dispute.created", "amount": 4200, "currency": "usd"}

type == 'charge.dispute.created' and amount > 1000

High-value disputes route to a human gate for review; the rest flow straight to automated handling — the standard human-in-the-loop pattern, now triggered by an external system instead of a click in the console.

Semantics worth knowing

• One webhook per workflow. Need fan-out from a single event source to several workflows? Point it at one workflow whose graph fans out into parallel branches
• No member attribution. The trigger is unauthenticated, so webhook-started runs are not attributed to any workspace member; they are identifiable in the audit trail by the webhook_run action
• Runs pin the current version. A run captures the workflow version at trigger time, so a graph edit mid-flight never changes an in-progress run
• Delivery is synchronous but execution is not. A 201 means the run was created and started, not finished. Senders that retry on a slow response would otherwise create duplicate runs — set a dedup_window_seconds and give each event a stable id, and a retry returns the original run instead. (The authenticated POST /api/workflows/{id}/runs endpoint offers the same guarantee via an Idempotency-Key header.)
• Rate limiting applies. When RATE_LIMIT_PER_MINUTE is set, the hooks path is subject to the per-IP ceiling like any other endpoint