First endpoint guide

# First endpoint guide

Canonical: https://docs.flowrelay.app/getting-started/first-endpoint/
Markdown: https://docs.flowrelay.app/getting-started/first-endpoint.md

Use this guide to prove one outside event reaches the Shopify Flow handoff before production traffic depends on it.

## Steps
Complete these in order.
1. Start with one path
   Start with one sender and one workflow. The basic path is external system -> FlowRelay endpoint -> Shopify Flow trigger -> FlowRelay receipt, then a separate Shopify Flow result check.
2. Gather the prerequisites
   Before starting, make sure FlowRelay is installed, the sender owner is available, you can edit a safe Shopify Flow workflow, and you have a synthetic test payload that does not contain customer data.
3. Enter the endpoint identity
   Enter an Endpoint name and Source label, such as Warehouse status to Flow and warehouse-partner, then choose which service will send the POST request.
4. Review the sender-aware recommendation
   FlowRelay recommends static-header authentication with X-FlowRelay-Secret for Zapier, Make, and n8n. It recommends exact-body HMAC-SHA256 with X-FlowRelay-Signature for custom HTTP/code. The Generic trigger, external.event, and no Shopify data access remain the ordinary starting point.
5. Change the trigger only when needed
   Open Change trigger when Flow needs a native Order, Customer, or Product reference, or the matching Inventory, Fulfillment, Return/refund, or Company/B2B context.
6. Open advanced controls only when needed
   Open Advanced authentication and mapping when a capable sender needs a deliberate authentication override or the payload needs custom event types, JSON paths, identifiers, or required fields. FlowRelay warns when a standard no-code sender is paired with HMAC.
7. Add the Flow trigger
   Add the matching FlowRelay trigger to a safe Shopify Flow workflow and enable it before sending the test event.
8. Prove the outside sender
   Use the in-app self-test to check FlowRelay first, then send one synthetic event from the actual outside sender. Setup progress records those as separate milestones and does not treat the self-test as proof that the sender is configured.
9. Read the proof 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.
10. Fix missing workflow readiness
   If the receipt says no_workflow, enable the matching FlowRelay trigger in Shopify Flow, confirm the variant matches the endpoint, then preview replay while the event is retained or ask the sender to resend a fresh test event.

## What you need
You need a Shopify store with FlowRelay installed, access to create a Shopify Flow workflow or a teammate who can, a sender system owner who can configure URL and authentication, and one synthetic test payload. Do not use real customer, order, token, endpoint secret, HMAC, or session data for the first proof.


## Choose Generic or a native reference trigger
Generic is the simplest first proof when Shopify Flow only needs to react to a custom event. Choose Order, Customer, or Product when Shopify Flow should receive a native Shopify resource reference from the sender payload. Choose Inventory, Fulfillment, Return/refund, or Company/B2B when the workflow belongs in that FlowRelay event lane and the sender can provide the required related resource context.


- Workflow need: Start a workflow from any external event; Suggested starting point: Generic; What to verify: The sender can send valid JSON and Shopify Flow can branch on the fields you mapped.
- Workflow need: Operate on an existing Shopify order, customer, or product; Suggested starting point: Order, Customer, or Product; What to verify: The sender provides the Shopify ID or GID at the mapped payload path.
- Workflow need: Handle inventory, fulfillment, return/refund, or company/B2B work; Suggested starting point: The matching operational lane; What to verify: The payload contains the related resource context FlowRelay needs for that trigger.

## Keep routing terms separate
When more than one endpoint or workflow uses the same trigger variant, add Shopify Flow conditions for the endpoint Source label and the resolved Event type so only the intended workflow path runs.


- Term: Source label; Meaning: The endpoint routing identity surfaced to Shopify Flow.
- Term: Trigger variant; Meaning: Selects the FlowRelay trigger payload and native-reference shape.
- Term: Default event type; Meaning: The fallback event label used when no mapped event-type path supplies one.
- Term: Resolved event type; Meaning: The mapped event-type value when present; otherwise the endpoint's default event type.

## Read the first receipt
A receipt should answer what FlowRelay accepted, which endpoint configuration was active, whether authentication and validation passed, whether Shopify Flow readiness existed, and whether FlowRelay handed the trigger to Shopify Flow. It is not a Shopify Flow run log and it cannot prove that downstream Flow branches, emails, tags, inventory changes, or app actions completed.


## If you see no_workflow
no_workflow means FlowRelay accepted the event but did not find a matching enabled Shopify Flow trigger for that endpoint and variant. Fix the Shopify Flow workflow first: add or enable the matching FlowRelay trigger, confirm the trigger variant matches the endpoint, and save the workflow. Then preview replay if the event is still retained, or send a fresh test event from the sender.


## First endpoint done criteria
The first endpoint is ready for cautious production traffic when the external sender reaches FlowRelay, external authentication passes, the external event receipt shows Delivered, the merchant separately confirms any downstream Shopify Flow run behavior they care about, the sender owner knows where the endpoint URL and auth material live, and support knows to use receipt IDs or diagnostics shares instead of raw payloads.


## 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
- [Create an endpoint](https://docs.flowrelay.app/setup/endpoints.md)
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md)
- [Add the Shopify Flow trigger](https://docs.flowrelay.app/setup/shopify-flow-trigger.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Support codes](https://docs.flowrelay.app/recover/error-codes.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.