Skip to main content

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).
The run receives the failure as its trigger payload:
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:
The input object is available in the workflow as {{trigger.data.*}} (and {{input.*}}). See Using the API.

Schedule

Run on a cron schedule:
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:
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:
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 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.
The approval covers the published version of the workflow — the steps that run, as published when it is approved, and the steps of every workflow it calls. Unpublished edits on the canvas, and a saved draft, are not covered: the trigger panel says which version an approval covers (“version 7 as published”), and while the canvas or a saved draft differs from the published version, Allow this workflow to receive request bodies is unavailable and the panel tells you to publish first. Publishing a workflow that holds no approval asks nothing; then Allow asks once. If the workflow is published again between your look and your click, the approval is refused and you are asked to reload. A change to the approved steps ends the approval: the next run gets metadata only, and the trigger panel says the approval has lapsed until an Owner or Admin approves again. That covers an Editor publishing an edit, a change to a workflow it calls, and a definition written through the API. The end is permanent: putting the approved steps back — restoring an earlier version, saving the old steps again, writing them through the API, changing a called workflow back, or deleting a called workflow and creating it again — does not bring the approval back. Only an Owner or Admin approving again does.Approving shows you every step first. Approve opens a list of every step of the published workflow and of every workflow it calls, with every setting saved on each step, exactly as stored, and which steps run after which. Secrets are masked: you can see that one is set, but not its value. The list is raw, so some of it is technical, and it is what runs: the canvas is for editing and can show less. A step with no earlier step starts when a run starts, even if it is not connected to the trigger, and the list says so. A workflow too big to show on that screen cannot be approved. A step can still choose where it sends at run time, from a secret, a connection, a variable or a route, and those values are not in the list.An Owner or Admin can keep the approval when they publish. When you publish a change to an approved workflow, Publish asks once, on one screen: keep sending the workflow request data, or publish without it. That screen shows the same list of every step as Approve does, for the version about to go live and every workflow it calls, and you can keep the approval once it has loaded. Keeping it asks for your security key or authenticator code, is recorded in the audit log, and moves the approval to the new steps in the same step, so the workflow does not run on metadata in between. You are asked when you publish, never while you edit, and saving a draft asks nothing. As with any publish, unsaved edits on the canvas are saved as the draft first, before that screen opens; if there are none, nothing is saved. If you cancel on that screen or at the verification, nothing is published and the edits stay saved as the draft. If someone else saved a different draft after you opened the workflow, or a workflow it calls changed after you read the list, the list or the publish is refused and you are asked to reload, so the approval never moves to steps you have not seen. If the list cannot be shown for another reason, the screen says why, and you can still publish without request data. That includes a draft too big to show, which cannot keep the approval. The same holds after you restore a version: Publish keeps the approval on the restored steps you are looking at. An Editor cannot keep the approval: they are told before publishing that it will end, and an Owner or Admin can allow request bodies again from the trigger panel. A publish does not restore an approval that has already lapsed, even if it publishes the exact steps that were approved. A workflow that calls another workflow chosen at run time cannot be approved. Request-triggered workflows that existed before approvals were introduced are not approved: they get metadata only until an Owner or Admin approves them. If one reads the request or response body, or filters on it, approve it.Field conditions see what the workflow sees. On a workflow that is not approved, a condition on 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 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.

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 to workflow.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