Safe bulk changes for Workflows

FastHook does not currently expose a bulk Workflow update endpoint. Apply repeated changes as individually reviewed Workflow updates with explicit version guards, bounded batches, canaries, and stop conditions. Do not turn a loop of API requests into an unreviewed fleet-wide mutation.

When a bulk change is appropriate

Good candidates are deterministic migrations with a clear match and replacement, such as changing one reusable Destination ID, updating one Action operation contract, or adding the same reviewed error route to a known group.

Avoid a bulk change when ownership is unknown, the Workflow list may be incomplete, graphs use materially different mappings, the provider side effect is not safely testable, or rollback cannot be prepared before mutation.

Create an immutable change manifest

{
  "change_id": "chg_2026_08_27_destination_rotation",
  "team_id": "tm_production",
  "match": {
    "kind": "destination",
    "resource_id": "dst_old"
  },
  "replacement": {
    "resource_id": "dst_new"
  },
  "targets": [
    {
      "workflow_id": "wfl_alpha",
      "expected_version": 8,
      "owner": "orders-platform",
      "approval": "approved"
    }
  ],
  "canary_workflow_id": "wfl_alpha",
  "batch_size": 5,
  "stop_conditions": {
    "workflow_conflicts": 1,
    "failed_canaries": 1,
    "unexpected_side_effects": 1
  }
}

The manifest must enumerate targets. Do not interpret “all currently returned Workflows” as approval, especially when the list endpoint returns its 255-record maximum.

Keep the reviewed before-graph, planned after-graph, and a semantic diff for every target. Exclude API keys, credentials, Trigger payloads, Step outputs, and provider secrets.

Plan phase

1. generate a complete Workflow inventory;
2. perform dependency impact analysis;
3. retrieve each target graph and record its current integer version;
4. apply the transformation in memory without sending an update;
5. validate that exactly the intended structured fields changed;
6. verify Step/Edge references, required mappings, Source, account, and resource ownership;
7. save before/after hashes and human approval; and
8. prepare a forward rollback payload for every target.

Fail the plan when a target no longer matches, an expected dependency is absent, more than the expected number of fields changes, or the current version differs from the reviewed version.

Apply phase

For each Workflow:

1. retrieve it again immediately before mutation;
2. compare its version and relevant graph fragment with the approved manifest;
3. send PUT or PATCH /v1/workflows/:id with the current version and complete intended graph fields;
4. verify the returned version increased by exactly one;
5. retrieve the saved graph and compare it with the approved after-state; and
6. append the Workflow ID, before/after versions, response time, and result to the change ledger.

FastHook returns HTTP 409 with workflow_conflict for a stale explicit version. Stop the batch and review the concurrent change; do not automatically fetch the new version and overwrite it.

Process a small bounded batch sequentially or with conservative concurrency. Provider and FastHook API limits still apply. The absence of an HTTP error does not prove the changed Workflow behaves correctly.

Canary and expansion

Apply the first update to one representative low-risk Workflow. Use a synthetic event and verify Audit plus the provider-side business result. Observe failure, latency, duplicate, Trigger-health, and reconciliation signals before expanding.

After each batch:

• confirm every requested update produced one expected version increment;
• run representative test events across distinct graph patterns;
• compare technical and business signals with baseline;
• check the monitor itself for incomplete result windows; and
• obtain the next expansion approval.

Do not activate many Draft or disabled Workflows in the same request loop. Lifecycle changes also increment versions and should have their own manifest, canary, and evidence.

Stop and recover

Stop on the first stale version, unexpected graph diff, authorization failure, missing resource, failed canary, incomplete inventory, monitor failure, or unexpected external side effect.

Rollback is another forward update using the latest current version. Reapply the reviewed before-state, keep the Workflow paused or controlled during validation, then canary and reconcile. A graph rollback does not undo provider Actions that already ran.

Finish with the Workflow release checklist and use Incident response if the change created incorrect or duplicate work.