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
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).
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:input object is available in the workflow as {{trigger.data.*}} (and {{input.*}}). See Using the API.
Schedule
Run on a cron schedule:Webhook
A Webhook trigger gets a signed, per-workflow URL on publish: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.
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: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 included only when the route keeps them and an Owner or Admin has approved the workflow. The trigger always carries the request method, path, headers (sensitive values masked), query parameters and IP, and the response status, headers and latency — everything you route and filter on. Editors can build and run request-triggered workflows either way. Two things decide the bodies, and both must say yes:
- The route keeps them. The route’s Discard request bodies and Discard response bodies switches for that environment are on by default. A discarded body reads
[body logging disabled]in the request log and in an approved workflow’s runs. Turn a switch off on the route’s Security tab to keep that side’s body. A response body also stays out if the request used a secret shared with your workspace under a use restriction: it reads[body not stored: this request used a secret shared with this workspace under a use restriction], whatever the switch says. - The workflow is approved. Whatever the route keeps, the bodies read
[body withheld: this workflow is not approved to receive request and response bodies]until an Owner or Admin opens the trigger and clicks Allow this workflow to receive request bodies, which asks for their security key or authenticator code and is recorded in the audit log.
request.body.… or response.body.… is evaluated against the withheld text, not the real body, so it cannot filter on the body: a positive match (equals, contains, regex) never fires, and a negative one (does not contain, does not equal) fires for every request. The same goes for an approved workflow on a route that discards that side: the condition reads [body logging disabled]. Conditions on the method, path, status, headers and query parameters work the same either way.A run that was handed bodies is checked again when it starts, when it resumes, when it calls a sub-workflow and when it is retried, against the workflows as they are then — and so is every sub-workflow run it launched. A run queued before a change runs with the bodies withheld. A run paused on a delay or an approval link, a sub-workflow run, a sub-workflow call and a retry from a step are refused with that reason in the run history, unless an Owner or Admin has approved the changed workflow by the time the run reaches that point. A refused run is shown as failed, but it does not start your error-handler workflows, does not count toward automatic disabling and does not send the workflow.execution.failed webhook event. The same goes for the run whose sub-workflow call was refused, or which was waiting on a sub-workflow run that was refused, when that step’s failure is what ends it — a call step set to continue on error carries on as usual. A refused run is finished: it does not resume when the workflow is approved again. Approve the workflow, then retry the run.Run history of a run that was handed bodies shows structure only. For such a run — and every sub-workflow run and retry launched from it — the run view, the run lists, the builder’s sample data and the copilot’s explanation show the field names and nesting of each step’s input and output with every value replaced by its type (<string>, <number>, <boolean>), and the error text is withheld, for every role. Step names, types, statuses and timings are unchanged. An Owner or Admin can click Reveal request data on a run, which asks for their security key or authenticator code and is recorded. The Management API applies the same rule and has no call that returns the values. A run that was not handed bodies (an unapproved workflow’s run, or a run whose route kept no body) is shown in full, including the method, path, status and masked header values.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 atPOST /hooks/apps/:token, are signature-verified over the raw bytes, and are de-duplicated so a provider redelivery runs the workflow only once.
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.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 toworkflow.execution.completed / workflow.execution.failed. See Using the API.
Next Steps
Connections
Connect the apps that power app triggers
Using the API
Execute and manage workflows via /v1