Skip to main content

Snapshots & the Webhook Payload

Everything your workflow needs to do its job arrives in one place: the webhook payload that Circus POSTs to your trigger. And the most important thing in that payload is a set of snapshots — frozen copies of the operator's configuration, captured the instant the run started.

Why snapshots exist​

When a run begins, Circus takes an immutable snapshot of all the configuration it will use and sends it along. Because it's frozen at start time, two things follow that matter to you:

  • The run uses a consistent configuration from beginning to end — even if the operator edits something mid-run, your execution keeps using what it started with.
  • The run is reproducible — which is exactly why a retry replays the same snapshots rather than re-reading current config. A retry reproduces the original conditions; it doesn't quietly pick up changes.

The practical rule this leads to: don't hardcode configuration in your workflow — read it from the snapshot. If something you need isn't in the payload, that's a conversation with the operator (who controls the configuration), not a constant you bake into n8n.

The four snapshots​

The payload carries four snapshots, each covering one area:

  • workflow_config_snapshot — the agents, models, prompts, and their parameters. This is what the Agent node reads.
  • service_config_snapshot — the external services, with methods, headers, and resolved URLs. This is what you read when you build a service call yourself.
  • system_snapshot — system context and system-wide parameters, with overrides resolved.
  • workspace_snapshot — your plugin's domain-specific context for this piece of work.

Each has its own article; this section walks them one at a time.

Reading them​

You don't parse the raw request yourself. The Init node captures the payload, and downstream nodes read any snapshot through a shared helper (getSnapshot()) that pulls it from Init's output. The Agent node uses this automatically; when you read a snapshot in your own nodes, you reference the Init node's output — for example, the workspace snapshot's fields are available as expressions off the Init node. The key idea: the payload is read once at Init, and every Circus node draws from that same captured context.