Triggers

A workflow’s single trigger node decides when it runs. Beyond manual and API invocation, KnoxCall supports scheduled, webhook, route-event, and app-based triggers — all backed by durable, exactly-once delivery.

Trigger Types

Type	Fires when…
Manual	You run it from the UI or the API
Schedule	A cron expression comes due
Webhook	An HTTP request hits the workflow’s signed URL
Inbound Webhook	A shared inbound webhook fans out to this workflow
Route Event	A KnoxCall route processes a request (`proxy_event`)
App Event	A connected app sends a provider webhook (instant)
App Polling	Polling a connected app surfaces a new item
Another workflow fails	Any other workflow in this environment fails (`workflow_error`)

Triggers are synced from the workflow definition to a trigger registry on publish, so changing a trigger only takes effect when you publish.

Error handler — when another workflow fails

A workflow with the Another workflow fails trigger runs whenever a different workflow in the same environment ends in a failure. It is how you send failures to Slack, open a ticket, or page someone, without adding an error branch to every workflow you own. Scope. Leave Workflows to watch empty and it handles failures from every workflow in this environment — one handler is usually all you want. List specific workflows to narrow it. Three rules are enforced rather than left to configuration:

A workflow never handles its own failures. It is excluded from its own watch set.
An error handler’s own failure does not start another error handler. If it did, a broken handler would launch a copy of itself on every failure, forever. Its failure is recorded in the run history and stops there — so check that history if a handler goes quiet.
A disabled handler stays disabled. Turning one off stops it, including one KnoxCall turned off itself (see below).

The run receives the failure as its trigger payload:

{
  "execution": {
    "id": "…",
    "workflowId": "…",
    "workflowName": "Nightly sync",
    "triggerType": "schedule",
    "startedAt": "2026-09-10T10:00:00.000Z",
    "failedAt": "2026-09-10T10:00:05.000Z",
    "errorMessage": "Node http_1 failed: HTTP 500 from upstream",
    "sandbox": false
  }
}

Live and Test are separate: a Test-mode failure only ever reaches a Test-mode handler.

When a workflow keeps failing

After five consecutive failed runs, KnoxCall disables the workflow and emails the workspace’s owners and admins. Nothing is deleted, and successful runs before that point are untouched. The count is of consecutive runs, and a run only counts as failed once it has exhausted whatever per-node retry policy you configured — so five here means five genuine failures, not five attempts. A single successful run resets it. The workflow stays off until you turn it back on. KnoxCall will not re-enable it for you: the point is that somebody looks at why it broke first.

Manual & API

A Manual trigger runs on demand. From the API, queue a run against the public resource:

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -X POST https://api.knoxcall.com/v1/workflows/{id}/execute \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"input": {"any": "data"}}'

The input object is available in the workflow as {{trigger.data.*}} (and {{input.*}}). See Using the API.

Schedule

Run on a cron schedule:

Trigger Type: Schedule
Schedule: "0 * * * *"   # every hour, on the hour

Scheduling is exactly-once across the worker fleet — a due schedule fires a single run even with multiple workers, using row-locked claiming (no leader election, no duplicate runs).

Webhook

A Webhook trigger gets a signed, per-workflow URL on publish:

https://api.knoxcall.com/hooks/wf/{token}

POST your payload to it; the raw body is available in the workflow. The endpoint is rate-limited per token and supports bearer and HMAC signature verification. The payload is delivered as the trigger input.

The old admin route POST /admin/webhooks/workflows/{id}/trigger has been removed. Use the workflow’s /hooks/wf/{token} URL (or the /v1 execute endpoint) instead.

Inbound Webhook

If you already receive provider webhooks through a shared inbound webhook, target a workflow from it. Only verified deliveries fan out, and the match is pinned to the workflow’s mode (Live/Test).

Route Event

Fire when requests pass through your routes:

Trigger Type: Route Event      # underlying triggerType: proxy_event
Event Types:
  - request.completed
Route Filter: (optional)
Environment Filter: (optional)

Valid event types: request.received, request.success, request.error, request.client_error, request.server_error, request.timeout, request.completed. You can narrow matches with a route filter, environment filter, and field conditions.

Request and response bodies are not included. The trigger carries the request method, path, headers, query parameters and IP, and the response status, headers and latency — everything you route and filter on — but the payload bodies read [body logging disabled]. Proxied payloads are not copied into workflow run history unless the deployment has explicitly opted into body persistence (PROXY_LOG_BODIES, off by default, and the same switch that governs whether bodies appear in request logs). It is one decision for both stores: if your request logs show [body logging disabled], so will your workflow runs.

App Triggers

Connected apps (Connections) can start workflows two ways.

Instant (provider webhooks)

For apps that support it (e.g. GitHub issue-opened, Stripe events), publishing the workflow subscribes a provider webhook automatically; disabling or deleting the workflow unsubscribes it. Deliveries arrive at POST /hooks/apps/:token, are signature-verified over the raw bytes, and are de-duplicated so a provider redelivery runs the workflow only once.

Trigger Type: App Event
Connection: my-github        # a saved GitHub connection
Event: issue_opened

Polling

For apps without per-connection webhooks (e.g. Slack messages), KnoxCall polls on a schedule and fires on new items. The first poll arms the cursor without firing (so you don’t get a backlog flood), and polling errors back off automatically. One poll starts at most 25 runs. A burst bigger than that is not dropped: the poll starts the oldest 25, remembers the last item it started, and the remainder fires on the following poll — so a backlog drains at 25 items per polling interval, each item firing exactly once.

Trigger Type: App Polling
Connection: my-slack
Resource: new_channel_message

Delivery Guarantees

Exactly-once — schedules, polling, and instant webhook redeliveries all de-duplicate; a single logical event produces a single run.
Durable — a queued run survives a worker restart and resumes.
Mode-scoped — triggers only fire workflows in their own Live/Test mode.

Notifications on Completion

To be notified when a run finishes (rather than starting one), subscribe an outbound webhook to workflow.execution.completed / workflow.execution.failed. See Using the API.

​Triggers

​Trigger Types

​Error handler — when another workflow fails

​When a workflow keeps failing

​Manual & API

​Schedule

​Webhook

​Inbound Webhook

​Route Event

​App Triggers

​Instant (provider webhooks)

​Polling

​Delivery Guarantees

​Notifications on Completion

​Next Steps

Connections

Using the API

Triggers

Trigger Types

Error handler — when another workflow fails

When a workflow keeps failing

Manual & API

Schedule

Webhook

Inbound Webhook

Route Event

App Triggers

Instant (provider webhooks)

Polling

Delivery Guarantees

Notifications on Completion

Next Steps