Recover a failed handoff

# Recover a failed handoff

Canonical: https://docs.flowrelay.app/use-cases/recover-failed-handoff/
Markdown: https://docs.flowrelay.app/use-cases/recover-failed-handoff.md

Use this path when an event arrived but needs investigation before anyone retries or escalates it.

## When the workflow did not run
A typical case: the fulfillment partner marks an order shipped, the sender's log says the webhook succeeded, but the Shopify Flow workflow that tags the order never ran. Without a receipt, someone has to work out whether the event ever arrived, whether authentication passed, whether the workflow was enabled, or whether the failure happened after the handoff. The receipt answers those questions in order — and tells you which system owns the next step.


## Why receipts come first
The receipt is the evidence record. It tells a human or authorized agent what FlowRelay can prove without exposing private event details.


## Replay is not automatic
Replay can trigger downstream Shopify Flow actions. Treat it as an explicit recovery action with preview, authority, and audit.


## When to escalate
Escalate when the receipt or grant says the action is outside the current operator's authority, or when diagnostics are needed for support.


## Typical path
A typical path starts from the scenario, then moves into setup and verification.
1. Find the affected event
   Open Event history and filter to the endpoint, time window, or outcome you need to investigate.
2. Read the receipt
   Open the receipt and read the support code, readiness facts, retention state, and handoff status.
3. Follow the support code
   Use the support-code guide to decide whether the sender, endpoint, Shopify Flow workflow, or FlowRelay setup needs attention.
4. Preview replay only when safe
   Preview replay only when the retained request is still available and the operator understands downstream side effects.
5. Share redacted diagnostics
   Share diagnostics instead of raw event bodies when a partner or support team needs evidence.

## 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
- [Event history](https://docs.flowrelay.app/operate/event-history.md)
- [Support codes](https://docs.flowrelay.app/recover/error-codes.md)
- [Replay an event](https://docs.flowrelay.app/recover/replay.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.