Overview
The Cloudflare Worker that turns ShipHero fulfillment webhooks into Supabase shipment, order, customer, and zone data.
The ShipHero Handler is a Cloudflare Worker that receives fulfillment webhooks from ShipHero and writes the results into Supabase. It is the piece labelled "Cloudflare worker" in the Data Flows diagram: the service that turns a raw shipment payload into linked shipment, order, customer, store, and shipping-zone records.
It lives in its own repository,
supportkings/NC-shiphero-handler,
separate from the main portal.
One webhook, many writes
A single call to /process_shiphero_shipment can touch eight Supabase tables.
Every write first checks for an existing record, so the worker is safe to
replay. See Webhook Processing.
What it does
When ShipHero fulfills an order it POSTs a webhook to the worker, which then:
- Creates shipment records with tracking numbers, box dimensions, weights, and label costs.
- Verifies line-item quantities against the ShipHero API, because the webhook payload can under-report how much shipped.
- Links product SKUs with a two-tier lookup: Supabase first, then an n8n webhook fallback.
- Creates or links orders with pricing, tax, discounts, and shipping figures pulled from the ShipHero GraphQL API.
- Tracks customers from shipping addresses, deriving the US state from the ZIP code when it is missing.
- Creates stores on the fly from each order's
shop_name. - Calculates shipping zones from the warehouse and customer ZIP codes.
Tech stack
| Concern | Choice |
|---|---|
| Runtime | Cloudflare Workers |
| Framework | Hono |
| Database | Supabase (PostgreSQL) |
| Language | TypeScript (strict mode) |
| Error tracking | Sentry (@sentry/cloudflare) |
| Tooling | Wrangler |
The whole request handler is a single file, src/index.ts. All ShipHero
GraphQL queries and Supabase calls are inline. src/utils/supabase/types.ts
holds the generated database types.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | / | Health check that returns Hello Hono! |
POST | /process_shiphero_shipment?brand={n8n_id} | Main webhook for ShipHero fulfillment events |
The brand query parameter is the account's n8n_id; the worker uses it to
find the Brands row (and its ShipHero
access token) that owns the incoming shipment. CORS is enabled on every route.
Explore this section
Webhook Processing
The full pipeline behind /process_shiphero_shipment, step by step.
Quantity Verification
Why the worker re-checks line-item quantities against ShipHero, and how the kill switch works.
Shipping Zones & State Derivation
How zones are calculated and how US states are recovered from ZIP codes.
Configuration & Deployment
Environment secrets, Wrangler config, Sentry, and the auto-deploy flow.
Backfill Scripts
Standalone scripts that repair historical store, zone, and customer-state data.