Skip to main content

Configuring Workflow Engine Secrets

A workflow engine is a record operators create in the UI/API (name, type, webhook base URLs, API base URL). The secrets that authenticate traffic to and from that engine don't live in the database — they're environment variables on the server, keyed by the engine's slug. This split keeps secrets out of the database and out of the repo.

The slug-keyed variables​

Each variable ends in _{slug}, where {slug} is the engine's slug (for an engine slugged primary_n8n, the variable is ..._primary_n8n):

  • WORKFLOW_ENGINE_PRODUCTION_WEBHOOK_SHARED_SECRET_{slug} — the secret used to sign production webhook JWTs (HS256). The n8n webhook node must verify with the same secret, HS256 algorithm, passphrase key type.
  • WORKFLOW_ENGINE_TEST_WEBHOOK_SHARED_SECRET_{slug} — the same, for test webhook JWTs.
  • WORKFLOW_ENGINE_API_KEY_{slug} — the key sent as X-N8N-API-KEY on engine stop calls. Without it, stop calls go unauthenticated and the engine may reject them.
  • WORKFLOW_ENGINE_WEBHOOK_TIMEOUT_MS_{slug} — webhook dispatch timeout (default 60000).
  • WORKFLOW_ENGINE_STOP_TIMEOUT_MS_{slug} — timeout per stop attempt (default 120000).

All are optional — omit them for unauthenticated calls and default timeouts. But if you sign webhooks on the platform side, the engine must verify with the matching secret, and if the engine requires auth to stop executions, the API key must be set.

Why the two secrets, and why signing matters​

Production and test webhooks are signed with different secrets so that a test-mode workflow can never dispatch a validly-signed production call. The signing itself is the platform proving to the engine that a webhook genuinely came from Circus — see the architect's Webhook Authentication for the model.

A restart is required​

These are read at startup. After adding or changing any of them, stop and start the API container (not restart — see Day-2 Docker Operations) for the new values to take effect.

The uppercase-slug variant​

A few paths (notably engine stop configuration in troubleshooting) reference the slug in uppercase — e.g. WORKFLOW_ENGINE_API_KEY_PRIMARY_N8N. When diagnosing a stop failure, match the exact casing the error and the deployment guide use.