What a webhook integration pattern actually guarantees

A webhook integration pattern inverts the usual direction of travel. Instead of your middleware asking an ecommerce platform whether anything new has happened, the platform posts a small payload to an endpoint you control the moment an event occurs. For order sync this is attractive: an order placed at 14:02 can be in the warehouse queue by 14:02, and the operations team stops refreshing two screens to work out whether something has come through.

The guarantee on offer is narrower than most project sponsors assume. Webhooks are, almost universally, at-least-once delivery with no ordering promise. Shopify, for example, signs each payload with an HMAC and retries a failing endpoint repeatedly over roughly a two-day window before it gives up and flags the subscription as failing; it expects your endpoint to acknowledge within a few seconds. Those two facts together mean you will receive duplicates, you will occasionally receive an order-updated event before the order-created event that logically preceded it, and if your server is slow you will be retried even though you processed the message successfully.

There is also the question of what the payload contains. A webhook body is a snapshot of the record at the moment of the event, not a diff and not necessarily the current state. By the time you process it, the order may have been edited, partially refunded or cancelled. Treating the payload as a notification that something changed, then reading the authoritative record back from the API before writing anything downstream, removes an entire class of defect. It costs one extra API call per order, which is rarely material against a rate limit.

Finally, webhooks require you to run a publicly reachable, always-on endpoint with a valid certificate, signature verification and sensible handling of unauthenticated traffic. That is a modest piece of infrastructure, but it is infrastructure, and somebody has to own it after handover.

Where polling still earns its place

Polling has an unfashionable reputation and a very good production record. A poll is a query you control: you decide when it runs, what window it covers, and what happens when it fails. If a poll does not run, the next one covers the gap, because the cursor has not moved. That self-healing property is the single strongest argument for polling in order sync, and it is why almost every robust integration retains a polling component somewhere even when webhooks are available.

Polling is also the only option in a large part of the estate. Amazon Seller exposes change notifications through a queue-based mechanism rather than a simple HTTP callback, which is a different engineering shape from a webhook receiver and often not worth the complexity for a modest order volume; a scheduled query filtered by last-updated date is simpler to operate. eBay's order retrieval is comfortably driven by a modification-date filter. On the downstream side, finance and warehouse systems such as Sage 200, Mintsoft and Peoplevox generally expect you to ask them for changes rather than announcing changes to you, so the return leg of an order-to-cash flow is polling regardless of what the sales channel offers.

The mechanics matter more than the interval. A poll should use a server-side timestamp filter, not a client clock, and the cursor should be stored as the highest updated timestamp actually returned rather than the time the job ran. Overlap the window by a few minutes to absorb clock skew and indexing lag, and rely on idempotency downstream to discard the resulting repeats. Page properly, and treat an incomplete pagination run as a failed run that does not advance the cursor.

The cost of polling is latency and wasted calls. On a platform with tight limits — Shopify's leaky-bucket behaviour on the REST Admin API being the well-known example — a five-minute poll across several resource types can consume a meaningful share of your quota doing nothing useful for most of the day. That is the trade you are making: predictable recovery in exchange for predictable overhead.

The hybrid pattern most order syncs end up with

In practice the durable design is not a choice at all. It is a webhook integration pattern for latency plus a polling sweep for completeness, with a single idempotent processing path serving both. The webhook gets the order moving in seconds; the sweep guarantees that nothing is permanently lost because of a deployment, a certificate renewal, a DNS change or a platform-side delivery failure that exhausted its retries while your endpoint was down.

The sweep does not need to be frequent or wide. A query every fifteen minutes for orders modified in the last hour will catch the overwhelming majority of gaps at negligible cost. A separate daily reconciliation over the previous seventy-two hours, comparing order identifiers present in the channel against those present in the ERP or WMS, catches the residue and produces the exception report that finance actually wants. When a WooCommerce store is involved this second layer is not optional, because WooCommerce webhook delivery depends on the site's scheduled task infrastructure and a busy or cached site can delay or drop deliveries in ways that are invisible from the outside.

Both paths must converge on the same handler and the same idempotency key. If the webhook route creates an order one way and the polling route creates it another, you have built two integrations with one budget and you will spend the difference in support. The key should be derived from the source system's immutable order identifier, stored with a unique constraint, and checked before any write to the destination.

One caveat on ordering. Because webhooks arrive out of sequence, the handler should compare the version or updated timestamp of the incoming record against what it last processed and discard anything older. Without that check, a delayed order-created event can overwrite a later cancellation, and the warehouse picks something the customer no longer wants.

Building a receiver that holds up under load

The single most common cause of webhook loss is doing the work inside the request. If your endpoint validates the signature, calls the ERP, writes to the WMS and then returns, you are betting that the entire downstream chain responds inside the platform's timeout. On a morning when Sage 200 is slow, it will not, the platform will retry, and you will process the same order two or three times concurrently.

The correct shape is short: verify the signature, persist the raw payload with its headers and a received timestamp, return a success status, and process asynchronously from a queue. This also gives you replay for free — when a mapping bug is found on Thursday, you can reprocess Monday's stored payloads rather than asking the client to re-trigger orders.

  • Signature verification before parsing — Compute the HMAC over the raw request body. Parsing and re-serialising first will break the comparison, and a receiver that accepts unsigned traffic is an open write path into the ERP.
  • Persist first, process second — Store the payload verbatim. The stored copy is your evidence when a discrepancy is raised weeks later and your replay source when a transformation needs correcting.
  • A dead-letter queue with a human owner — Messages that fail repeatedly must land somewhere a named person reviews daily, with enough context to act. Silent discard is how three orders a month disappear for a year.
  • Monitoring on absence, not just errors — Alert when no webhook has been received for longer than the quietest plausible gap for that client's trading pattern. A dead subscription produces no errors at all.
  • Endpoint versioning — Use a versioned path so payload schema changes can be adopted without breaking the live subscription, and keep the old version running until the platform confirms no traffic remains.

Choosing between the patterns during discovery

The decision belongs in discovery and data mapping, not in build, because it changes the hosting requirement, the testing approach and the handover documentation. Four questions settle it in most cases. First, what is the genuine latency requirement — a same-day courier cut-off at 15:00 justifies webhooks, whereas a next-day dispatch operation that picks in two waves does not. Second, what does the source platform actually support, and with what retry behaviour. Third, can the client's environment host a public endpoint, or is everything behind a firewall with no appetite for an inbound rule. Fourth, what is the volume, because a platform that sends an event per line item on a large B2B order will generate far more traffic than the order count suggests.

Volume and shape often push in opposite directions. A BigCommerce store dispatching two hundred orders a day is comfortably served by a five-minute poll, and the simplicity is worth more than the four minutes of latency saved. A Shopify B2B account with large baskets and a tight courier deadline benefits from webhooks, but needs the polling sweep behind it precisely because the cost of a missed order is higher.

Whichever pattern is chosen, write down the recovery procedure and hand it over with the code. It should state where stored payloads live, how to replay a date range, how to reset a polling cursor, what the reconciliation report looks like and who receives it. An integration that recovers in ten minutes because the procedure is documented is a different operational proposition from one that recovers in two days because the only person who understood it has moved on.

If you are weighing up a webhook integration pattern against polling for an order flow of your own and want the trade-offs examined against your actual volumes and systems, we are happy to talk it through on 01303 883111 or at hello@api-integrations.co.uk.

Key points

  • Webhooks give latency, not completeness: they are at-least-once, unordered, and retries eventually expire, so a polling sweep behind them is a requirement rather than a refinement.
  • Both delivery routes must converge on one idempotent handler keyed on the source order identifier, with a version or timestamp check so an out-of-order event cannot overwrite a later state.
  • Acknowledge the webhook within seconds, persist the raw payload and process asynchronously; the stored payloads then provide replay, evidence and a documented recovery path at handover.