Workflow versioning and migrations

Every successful Workflow create starts at version 1. Every successful update increments the version and stores an immutable graph snapshot containing the Workflow metadata, Source, Steps, Edges, mappings, Action configuration, and schema provenance available at save time.

What creates a new version

The Workflow update endpoint accepts metadata, status, Source, Steps, or Edges. A successful update increments the version even when the request changes only the lifecycle status.

Builder operations such as adding, editing, renaming, enabling, disabling, duplicating, or deleting a Step save the graph and therefore create a new version. Editing or duplicating a Path also saves a new graph version.

Optimistic concurrency

Send the current integer version when updating a Workflow. If another editor has already saved a newer version, FastHook returns HTTP 409 with code workflow_conflict instead of overwriting that change.

On conflict:

1. retrieve or reload the Workflow;
2. compare the current graph with the change you intended;
3. reapply only the still-valid change; and
4. save using the newly returned version.

Do not automatically retry the same stale update body. It can replace newer mappings or routes after an unsafe client-side merge.

What Audit preserves

A run records the Workflow version used when the run was created. Run detail can expose:

• version number and version creation time;
• Workflow name and Source ID from that snapshot;
• graph SHA-256;
• snapshot_status and whether the snapshot is exact;
• Trigger schema provenance;
• ordered Step identity and kind;
• Action provider, operation, schema provenance, and stored configuration evidence;
• input route, output port, response status, output digest, and failure data.

snapshot_status: exact means FastHook has the immutable snapshot for that version. legacy_unavailable identifies an older migrated run whose historical graph could not be reconstructed exactly. FastHook reports that limitation instead of presenting the current graph as historical truth.

Payload previews have separate retention, size, and redaction rules. An exact graph snapshot does not guarantee that every Trigger input or Step output preview remains available.

Provider schema changes

Trigger and Action manifests can add fields, scopes, validation, or operations. A saved version captures schema provenance so Audit can distinguish the contract used by an older run from the current provider catalog.

Before changing an operation:

1. open the current provider reference and Action editor;
2. compare required scopes and reconnect if necessary;
3. check whether required input fields or output paths changed;
4. update downstream mappings that read the changed Step output;
5. test provider errors and rate limits; and
6. record the new Workflow version after the controlled run succeeds.

Migrate a graph safely

For a small change, pause the Workflow, edit the graph, test with a controlled Source event, then reactivate it.

For a high-risk change, create a separate Draft copy with a test Source and non-production accounts. Validate the new graph independently, then activate the replacement and pause the old Workflow in a controlled cutover.

Use these migration boundaries:

• Preserve the old Workflow while its recent runs are still needed for comparison.
• Do not reuse production credentials in a staging team unless the permission boundary explicitly allows it.
• Rebuild mappings when the Trigger or an ancestor Step changes shape.
• Treat reordered side effects as a business behavior change, not a visual-only edit.
• Test unmatched Paths and error routes, not only the happy path.
• Account for queued retries and long Delays before decommissioning the old route.

Rollback is a forward change

The current dashboard and public Workflow API do not expose a restore-version endpoint. Historical snapshots support execution evidence; they are not editable templates.

To recover from a bad release:

1. pause the affected Workflow to stop new runs;
2. inspect the last successful run and its version evidence;
3. restore the known-good configuration from your reviewed API payload, change record, or maintained copy;
4. save it as a new version;
5. run a controlled event; and
6. reactivate only after the provider-side result is correct.

This preserves the incident version and the recovery version in Audit. If you manage Workflows through the API, keep reviewed graph payloads in your own change-control system because run detail is not a full graph export endpoint.

Delete versus retain

Deleting a Workflow removes the Workflow and its dependent version/run data through the database lifecycle. Pause or disable it when historical operational access is still required. Delete only after retention and incident-review requirements are satisfied.

Continue with Workflow runs and errors, Workflow templates and duplication, and the production-readiness checklist.