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 can reach Shopify Flow before production traffic depends on it.

## Steps
Complete these in order.
1. 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. 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 JSON test event that does not contain customer data.
3. Create one endpoint in FlowRelay and name it for the sender and workflow, such as Warehouse status to Flow.
4. Choose the trigger variant. Use Generic when Shopify Flow only needs a custom external event; use Order, Customer, or Product when Flow needs a native Shopify reference; use Inventory, Fulfillment, Return/refund, or Company/B2B for those operational lanes.
5. Choose authentication. Prefer HMAC-SHA256 when the sender can sign the request body; use static-header authentication when it cannot.
6. Add the matching FlowRelay trigger to a safe Shopify Flow workflow and enable it before sending the test event.
7. Send one synthetic event from the sender or in-app test path, then open the FlowRelay receipt.
8. Treat Delivered as proof that FlowRelay handed the trigger to Shopify Flow, not proof that downstream Shopify Flow actions completed.
9. 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 safe synthetic JSON event. 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 fastest 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.; Best 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.; Best 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.; Best starting point: The matching operational lane; What to verify: The payload contains the related resource context FlowRelay needs for that trigger.

## 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 synthetic event from the sender.


## First endpoint done criteria
The first endpoint is ready for cautious production traffic when one synthetic event is accepted, the receipt shows Delivered, the merchant separately confirms any downstream Shopify Flow 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 include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.