Skip to main content

The Webhook Trigger & Init Node

Every Circus workflow begins the same way: a Webhook trigger, immediately followed by the Init node. Together they're the entry point — the platform dispatches a run to your webhook, and Init turns that incoming request into the shared context the rest of your Circus nodes depend on.

The webhook trigger​

Circus starts a workflow by making a POST request to a webhook, so your workflow must begin with an n8n Webhook node configured to accept POST. When the operator registers this workflow in Circus, the only thing they need from you is the webhook's identifier (its path) — Circus combines that with the engine's base URL to reach your workflow. If you want the webhook protected, that's the next article.

The POST body is the webhook payload — everything your workflow needs to do its job, including immutable snapshots of the operator's configuration. You'll read those via the Init node's output (see Snapshots & the Webhook Payload).

The Init node​

Place Init directly after the Webhook node — it must be the first Circus node, and downstream nodes will error if it isn't there. Init does four things:

  1. Validates the payload — it checks that a body and a workflow_execution_id are present, and fails clearly if the node was misplaced.
  2. Validates the webhook JWT, if one is present (see the next article).
  3. Stores the execution context — the workflow execution ID, n8n's own execution ID, and this node's name — in n8n's execution data, so every downstream Circus node can retrieve it through a shared helper.
  4. Registers the start of the run with the platform (best-effort — if that call fails, the run still proceeds).

Why context matters​

The context Init stores is the thread that ties the whole run together. Every other Circus node — Agent, Log, Complete, Terminate — reads it to know which platform execution it belongs to and where to call back. That's why Init is non-negotiable and always first: without it, the rest of your Circus nodes have nothing to anchor to. You also configure the Circus API key credential on Init (and the other nodes) so those callbacks can authenticate — covered in The Circus API Key Credential.