foliot docs

Concepts / Webhooks

Webhooks: one command, no notifications

Foliot makes exactly one outbound call, and it is a command, not a notification. The task push tells your app to execute a step and waits for the answer — the run is blocked until you respond. See the task webhook below for the payload, the signature and the response contract.

Foliot does not push event notifications. There are 26 event types in a run’s history — run.failed, run.stuck, step.exhausted and the rest — and none of them are delivered anywhere. There is no subscription endpoint, and looking for one is the most common wrong turn in this API.

To observe runs, pull:

  • GET /apps/{appId}/workflows/{workflow}/health — counts by status, where runs are sitting, and oldestDueAgeMs, which is the scheduler-lag signal worth alerting on. The cheapest thing to poll.
  • GET /apps/{appId}/runs?status=failed&status=stuck — the runs needing attention.
  • GET /apps/{appId}/runs/{runId}/events?after=<id> — one run’s history, incrementally.
  • GET /metrics — Prometheus, labelled by workflow and step.