Webhooks vs APIs vs Polling: How to Keep Two Systems in Sync

“The store says it went through. Why can’t Sara see it?”

Monday at Sandline. Sara is looking for Northbay Hotels' order: 40 boxes of NG-200.

Everyone agrees it exists. They disagree about where.

The webhook vs API question starts here. Should the store tell us, or should we ask? Let's follow the order, then find what “sent” really proves.

Webhook vs API: who starts the exchange?

A webhook is a notice sent to an address when an event happens. You subscribe to the event you want. In Shopify's setup, that means choosing a topic and a destination.

Think of a parcel at Sandline's desk. It says an order was created.

Someone opens it and starts work. Arrival doesn't mean the work inside is done.

Polling means asking for changes again and again. One read is a call. Repeat it on a schedule, and you have polling.

An API is an interface through which software makes requests. AWS explains the request-and-reply model. Polling can use that interface.

Webhooks can use it too. Shopify sends HTTP POST requests, as its delivery guide explains. So the choice is usually who starts: the source or your checker.

Webhook vs polling: which fits?

First ask how much delay the work can stand.

“Push is fast, pull is reliable” sounds tidy. But a notice can be late. A checker can fail too.

Our rule: push to start work promptly. Pull to check for gaps. Put a person in charge of both.

How does the Shopify order enter Beezr?

Karim chooses From a webhook in a Beezr workflow. He copies its URL and registers it in Shopify. That registration sets up the order-notice route.

Beezr stores the call in a durable queue, then returns 202 Accepted and a process ID, pid. The call survives a restart. Delivery is at least once, so steps must be safe to repeat.

HTTP's 202 definition means accepted for processing. Sara's order isn't finished yet.

Shopify counts responses in the 200 range as receipt. It wants a reply within a few seconds. Failed deliveries get retries over several hours, per its HTTPS guide.

Queue first, reply fast, work later fits that shape. Still, send a real test order. Check that Shopify counts Beezr's 202 as delivered.

Once approved, the order can go to accounting through a separate call. Follow it in the API guide. Don't treat each stage as the same thing: store notice, queue receipt, sales order, then invoice.

What if the webhook arrives late, twice or never?

Shopify says a notice may not arrive. Those in the same topic may arrive out of order too. Its advice: run separate checks for gaps, called reconciliation jobs.

What if the same notice arrives again? It should leave the intended result the same. That's called idempotent: a repeat of order 1042's notice shouldn't add an order.

That doesn't mean you can ignore all later changes. What if the order is cancelled, or the number of boxes changes? Decide how to apply those too.

Also test partial work. An order header might exist while line processing failed. Finding its ID doesn't prove every line is there.

How do you find orders nobody heard about?

Reconciliation means comparing both sides and checking the gaps. Shopify recommends periodic reads. Many queries support an updated_at filter to fetch changes since the last run.

Karim would rather find a gap at 7 a.m. than hear from a customer. Here's the separate check we recommend:

1. Read the source range. Fetch all pages. Record the period covered.
2. Match stable order IDs. Don't match on customer spelling or display labels alone.
3. Sort the gaps. Missing orders need intake; unfinished lines need repair. Changed orders need an update decision.
4. Recover safely. Keep the same business ID. Inspect partial results before replaying work.
5. Finish the whole check. Only then move its checkpoint. Assign unresolved gaps to an owner.

Beezr's Shopify connector can list orders and get an order. Design and own the schedule, comparison and checkpoint around those reads.

A checker can hide work too. If it marks a whole range done after reading half, it misses orders. Ask to see a failed check restart.

In our example, the check finds store order 1042 missing. Sara reviews its 40 boxes of NG-200. Recovery uses the agreed intake path, then checks the record and lines.

Who may send the webhook?

The address is a delivery door. Anyone who finds it can knock. Shopify signs each delivery and asks receivers to verify its signature.

Other senders may put a shared key in a header. In Beezr, requiring a key is a per-workflow choice. Sandline's Shopify workflow receives the payload the store posts.

For senders that can add headers, require a key in api-key. Each system can have its own key, paused on its own. Karim should list senders, decide how to trust each, and keep URLs out of shared documents and chats.

Sandline Supplies is a fictional example company.