Skip to main content

Registering Workflow Engines

Your workflows don't run inside Circus — they run in an external workflow engine (n8n today). Before you can create a workflow, you register at least one engine, so Circus knows where to dispatch runs and how to reach the engine's API. No engine is seeded by default; the URLs are specific to your deployment.

What you register​

Each engine has a name, an engine type (n8n or other), and three base URLs:

  • a production webhook base URL — where production runs are dispatched;
  • a test webhook base URL — used when you run a workflow with the "test webhook" option;
  • an API base URL — how Circus talks to the engine's API (for example, to stop a running execution, or to check its status from the background reconciler).

From the name, Circus generates a unique, immutable slug — immutable because per-engine environment-variable names are derived from it. Enter only the base URLs: the platform appends path segments like /webhook, /webhook-test, or /api/v1 itself, so you should not include them. URLs must use http:// or https:// (no reachability check is performed), and engines can't be deleted in this version.

The local-Docker gotcha​

This one trips people up. When you run Circus and n8n in Docker on the same machine, your n8n is at something like localhost:5678 — but you cannot use http://localhost:5678 as the base URL. Inside the Circus container, localhost means the container itself, not your host machine. Use http://host.docker.internal:5678 instead (unless your setup is configured differently).

Base URL on the engine, identifier on the workflow​

Notice the split: the base URL lives on the engine, while each workflow carries only a short webhook identifier. Circus combines the two at dispatch time to build the full URL. That's deliberate — update an engine's base URL once and every workflow using that engine follows along, with no need to touch individual workflow rows.

Per-engine secrets and timeouts (webhook signing secrets, the engine's API key) are set as environment variables, not in this UI — that's an operations task. See the Ops Engineer docs.