Naviga order middleware: seven sync flows, no webhooks

HubSpot is the orchestration and visibility layer in this design, not the system of record. Reps capture order intent in the portal, the backend confirms it, and the portal shows the result. Naviga stays authoritative for books, subscriptions, pricing and confirmed orders. That split only works if the portal is kept current, and the backend gave us little to work with.

Discovery tested every endpoint the design depended on against live responses rather than against documentation. Three answers shaped everything after it. There are no webhooks for this integration scope, so the middleware has to ask rather than be told. Customer records return a create date and no modification date, so a polling job has no way to request the customers that changed. Subscription reads are per customer with no date filter, and the order list endpoints were not usable in that environment at the time, so order discovery could not be assumed either.

One more constraint came from the data. Duplicate email addresses are normal in this customer base, and HubSpot allows one contact per address, so the sync had to carry the duplicates rather than reject them.

All seven flows run through one pipeline, in the same six stages: trigger, acquire the flow lock, read the source, normalize and match, write, persist the checkpoint. A flow that is already running exits as skipped instead of racing itself, and every run ends in one of five states an operator can read.

Customer discovery walks forward through backend customer identifiers from a saved checkpoint and stops after a long run of consecutive misses, because there is no changed-since call to make. It stores a snapshot and a payload hash per customer. A second flow runs continuously over those snapshots, re-fetches a customer, compares the hash and writes only when the payload actually changed. That pair replaces the delta query the API does not offer. Duplicate addresses survive as plus-addressed variants rather than being dropped.

Products and orders both run from a watermark. The order flow caps each run at a 24 hour changed window, so a long outage cannot become an unbounded batch. It dedupes the summaries, hydrates each order, upserts orders, line items and subscriptions, then runs associations as a separate pass. When every hydration in a run fails, the checkpoint holds rather than advancing, so no window is skipped quietly. Associations that do not resolve go to a backlog table that a repair flow retries.

Two flows run the other way. One searches HubSpot deals sitting at a validation stage, asks the backend to preflight the order, writes the returned pricing onto the deal and its line items, and moves the stage. A later pass creates the order in the backend, writes the backend order number onto the deal, and puts any backend error on a property instead of in a log. The second outbound flow sends companies and contacts changed since the last watermark back as accounts.

Orders, line items and subscriptions land in the portal on the hour with their associations already wired, and the deal carries the backend’s own validation result rather than a rep’s guess. Because every flow writes a run record and a checkpoint, a bad hour is a replay rather than a re-import: an operator picks the run, queues it, and the flow resumes from its saved watermark.

Most of what keeps it steady sits in the watermark handling. A window with no orders still advances the watermark, so an empty night is not rescanned forever. A window where every detail lookup fails holds the watermark instead. Failed associations queue and are repaired a quarter past the hour rather than vanishing into a log line. Discovery settled 79 properties before the flows were designed: 49 mapped directly, 23 needed a transform or a second call, and 7 exist nowhere in the source, which is now a documented omission rather than a surprise during user acceptance testing.

One deployable service on Railway: Node, Fastify, and Prisma over PostgreSQL. Six flows run on cron, five at the top of the hour and association repair a quarter past, and the seventh runs as a self-scheduling loop. HubSpot calls are pinned to API version 2026-03.

Every outbound call to either system passes through a limiter with three priority classes, and the backend limiter adds a per-flow concurrency cap so one flow cannot starve the others. PostgreSQL holds five tables: runs, checkpoints, replays, customer snapshots and the association backlog. Operations is an HTTP surface rather than a console: health, a manual trigger for one flow or all of them, replay with an optional immediate run, run history, and a state endpoint that returns locks, limiter statistics and recent replays.

The scheduler starts every flow. Four flows read the backend and write the portal, two read the portal and write the backend, and one drains a backlog table. Every run writes its status and its checkpoint to PostgreSQL, and the ops API can trigger or replay any of them. Nothing enters the service as an event of its own: both directions are discovered by a query rather than announced by one.

Every key in that table is a backend identifier held in a custom HubSpot property, never a name and never an email address. Names change when someone tidies a record, and one address can belong to several people in this customer base, so both make unreliable keys. Orders, line items and subscriptions are custom objects rather than deals, because a deal is a pipeline record that a rep moves and these are backend facts a rep should read. The one key that is not a lookup is the line item id: a line arriving without one fails the run rather than landing as half a record.

Ten rows of the property mapping, field names only: