# Swap over to FlowRelay

Canonical: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/
Markdown: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay.md

Use this when one existing event lane works, but every failure still turns into guesswork across sender logs, middleware, Shopify Flow, and support notes.

## Why swap over
FlowRelay is useful when the brittle part is not just receiving a webhook. The hard part is knowing what arrived, what auth passed, what mapping was active, whether Shopify Flow was ready, whether a replay is safe, and what evidence support or an authorized agent can use without digging through scattered logs.


## Start before FlowRelay exists
A pre-adoption merchant may not have any FlowRelay endpoints, receipts, or plan data yet. Start with a candidate lane inventory built from Shopify Admin context, current webhook or automation apps, provider exports, middleware runbooks, serverless functions, logs the operator can safely summarize, and merchant knowledge. Label every row with its evidence source, confidence, access gap, and next evidence step. Do not ask for endpoint secrets, raw payloads, auth header values, customer data, tokens, copied private logs, or store passwords.


- Field: Sender/source; Good evidence: Provider, app, middleware, serverless function, ERP, WMS, CRM, or manual process name; If missing: Ask the operator which system currently initiates the work.
- Field: Receiver/current path; Good evidence: Webhook app, middleware URL owner, script, queue, Zapier/Make lane, or Shopify Flow trigger clue; If missing: Mark as access gap; do not guess from unrelated FlowRelay data.
- Field: Shopify Flow tie; Good evidence: Workflow name, trigger name, condition text, log marker, or operator-confirmed downstream action; If missing: Treat as suspected only and require Shopify Admin review before cutover.
- Field: Pilot safety; Good evidence: Low volume, reversible action, harmless test branch, clear rollback owner, and a test path with synthetic data; If missing: Do not choose the lane as the first pilot.

## Safe migration sequence
Use one pilot before the broader cutover. The sequence is: create endpoint, wire a test sender, enable the Shopify Flow workflow, send a test event, verify the receipt, then cut over the production sender. Do not change the sender URL/auth or production traffic before the receipt proof and rollback owner are clear.


- Step: Create endpoint; Proof to collect: Endpoint name, trigger variant, auth mode, required mapping paths, and plan fit; Stop if: The trigger variant or required Shopify reference is unclear.
- Step: Wire test sender; Proof to collect: Synthetic payload, private auth configuration, and expected external event ID behavior; Stop if: The sender owner cannot test without exposing secrets or customer data.
- Step: Enable Flow workflow; Proof to collect: Matching FlowRelay trigger is enabled and the test action is safe; Stop if: The workflow might perform customer-visible or irreversible actions during the pilot.
- Step: Verify receipt; Proof to collect: Accepted or Delivered status, support code if any, replay state, diagnostics-share availability, and downstream Flow check; Stop if: The result is no_workflow, mapping failed, auth failed, or downstream behavior is unconfirmed.
- Step: Cut over; Proof to collect: Cutover window, rollback path, sender owner, monitoring cadence, and stop conditions; Stop if: Rollback cannot be performed quickly or plan capacity is not sufficient.

## What FlowRelay adds during migration
Receipts make each event discussable. Replay previews show whether retained material can be handed to Shopify Flow again and what side effects may repeat. Diagnostics shares let a partner or support team inspect redacted setup and receipt facts. Idempotency helps suppress accidental duplicate sender retries and keeps approved actions tied to the preview that created them. Endpoint secrets keep sender access private, and Flow handoff status separates FlowRelay proof from downstream Shopify Flow behavior.


## Why this is easier to trust
The change is not that events move faster. It is that every event now leaves an evidence trail — a receipt, a support code, a replay state, a diagnostics share — so a failure becomes a question you can answer instead of one you have to reconstruct. Human and authorized agent operators work from those stable facts instead of reconstructing them.


## Keep the old path until the new one is proven
The current webhook app, custom code, or manual process got the store this far — treat it as infrastructure to replace carefully, not a mistake to delete. Keep it available as the rollback path until the FlowRelay receipt proves the pilot lane works end to end, and only then retire it lane by lane.


## Cutover checklist
Before production cutover, confirm: the pilot endpoint shows Delivered (FlowRelay handed the trigger to Shopify Flow), downstream Shopify Flow behavior was checked separately, production sender auth is ready, rollback owner is available, plan capacity fits expected traffic, diagnostics sharing is available, and support knows not to ask for raw payloads, endpoint secrets, auth headers, tokens, or session data.


## Typical path
A typical path starts from the scenario, then moves into setup and verification.
1. Inventory candidate lanes from available evidence first: sender/source, current receiver or app, auth category, owner, event volume, criticality, retry behavior, rollback path, suspected Shopify Flow workflow, evidence source, confidence, and access gaps.
2. Choose one low-risk pilot lane before moving production traffic broadly.
3. Create the FlowRelay endpoint and choose the matching trigger variant and authentication method.
4. Wire a test sender or sandbox sender to the FlowRelay endpoint without changing the production sender yet.
5. Enable the matching Shopify Flow workflow with a harmless test action or controlled pilot branch.
6. Send one test event with synthetic data and verify the FlowRelay receipt, support code, replay availability, and diagnostics-share path.
7. Only after proof, cut over the production sender URL/auth for the pilot lane during an agreed window.
8. Monitor event history, receipts, usage, and downstream Shopify Flow behavior, then expand lane by lane.

## Handoff Boundary
Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.

## Related
- [First endpoint guide](https://docs.flowrelay.app/getting-started/first-endpoint.md)
- [Endpoint swap plan](https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md)
- [Shopify Sidekick](https://docs.flowrelay.app/agent-access/shopify-sidekick.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.