Brandbrand
Book a call
Blue network cables running from both sides into a row of ports with green and yellow lights

What Shopify webhooks are, and how to process them reliably

Shopify sends your app a message as soon as something happens in your store, but it does not promise that it arrives exactly once, or in order. What a webhook contains, where it goes wrong, and how we process them without missing an order.

Shopify tells you, your app does not have to ask

A webhook is a message Shopify sends to your app as soon as something happens in the store. A customer places an order, a product gets a new price, a merchant removes the app. Each kind of event is called a topic, such as orders/create or products/update. Your app subscribes only to the topics it needs.

Without webhooks, your app has to keep asking Shopify whether anything has changed. That is called polling. It costs API budget and you are always a step behind. With a webhook you hear about it almost at once.

Usually Shopify sends the message to an HTTPS address of your app. It can also go to Google Cloud Pub/Sub or Amazon EventBridge, if your app already runs there.

What a webhook contains

The message itself is JSON, by default with the whole object, such as the full order. With include_fields you limit it to the fields you use, with filter to the events that matter. Shopify also sends a set of headers:

  • X-Shopify-Topic says which event it is, for example orders/create.
  • X-Shopify-Shop-Domain is the myshopify.com address of the store.
  • X-Shopify-Hmac-Sha256 is the signature. With it you check that the message really comes from Shopify.
  • X-Shopify-Webhook-Id is unique per delivery. If the same ID arrives twice, it is a repeat.
  • X-Shopify-Triggered-At is the moment Shopify started the delivery.

Three things Shopify does not promise

Shopify is clear about this in its own documentation. A webhook arrives:

  • Not always exactly once. After a timeout or a retry, the same message can come in again.
  • Not guaranteed in order. Not even within one topic. A change from 10:02 can arrive before the one from 10:01.
  • Not guaranteed. A message can also never arrive.

On top of that, Shopify does not wait long. Your app gets one second to accept the connection and five seconds for the whole request. Any answer outside the 200 range counts as an error, a redirect too. Then Shopify tries again eight times over four hours.

In the app configuration or through the API

You can subscribe in two ways. In shopify.app.toml, the app's configuration file, the subscription applies to every store that installs the app. Shopify recommends this, unless topics or addresses differ per store. Through the GraphQL Admin API you create a subscription per store.

You notice the difference when things go wrong. A subscription made through the API that fails eight times in a row is deleted by Shopify, with a warning to the developer's emergency address. A subscription in shopify.app.toml stays. And if you are subscribed to the same topic twice, you get every message twice. In one of our apps, the old API subscriptions were still there after the move to shopify.app.toml. We cleared them out with a command of our own. The subscriptions from the file stay in place.

How we process a webhook

Because Shopify promises so little, our app does as little as possible at the moment a webhook comes in. Check, store, answer. The real work comes afterwards, on the queue.

From event to processed

  1. Something happens in the store. Shopify sends a webhook to the app.
  2. The app checks the signature. If it does not match, it answers with 401.
  3. The app stores the message under the webhook ID, puts the work on the queue and answers at once.
  4. A worker processes the message. A repeat or an older message is skipped.
  5. A periodic check fetches from Shopify what has changed, for messages that never came.
// Check, store, put on the queue and answer at once.
public function __invoke(Request $request)
{
    $hmac = base64_encode(hash_hmac('sha256', $request->getContent(), config('services.shopify.secret'), true));
    abort_unless(hash_equals($hmac, (string) $request->header('X-Shopify-Hmac-Sha256')), 401);

    // webhook_id is a unique column: a repeat is not stored again.
    DB::table('webhook_deliveries')->insertOrIgnore([
        'webhook_id' => $request->header('X-Shopify-Webhook-Id'),
        'topic' => $request->header('X-Shopify-Topic'),
        'shop' => $request->header('X-Shopify-Shop-Domain'),
        'payload' => $request->getContent(),
    ]);
    ProcessOrderWebhook::dispatch($request->header('X-Shopify-Webhook-Id'));

    return response()->noContent();
}
app/Http/Controllers/ShopifyWebhookController.php

A repeat or an older message

The task on the queue first checks whether this webhook ID has already been processed. If so, it was a repeat and it stops. The task is unique per webhook ID, so two copies never run at the same time.

Then the order. Every order has an updated_at. The app keeps it with its own copy, and only writes when the message is newer. An old message that arrives late can never overwrite a newer state.

public function handle(): void
{
    $delivery = WebhookDelivery::where('webhook_id', $this->webhookId)->firstOrFail();
    if ($delivery->processed_at) {
        return; // Already processed: this was a repeat.
    }

    $data = json_decode($delivery->payload, true);
    $order = Order::firstOrNew(['shopify_id' => $data['id']]);
    $changed = Carbon::parse($data['updated_at']);

    // Only write when the message is newer than what we already have.
    if (! $order->exists || $order->shopify_updated_at->lt($changed)) {
        $order->fill(['status' => $data['financial_status'], 'shopify_updated_at' => $changed])->save();
    }

    $delivery->update(['processed_at' => now()]);
}
app/Jobs/ProcessOrderWebhook.php

Mistakes we made ourselves

  • Copies from the store settings. In one store, besides the app, there were webhooks created by hand under Settings > Notifications in the Shopify admin. Those are signed with a different secret. Our app rejected them with a 401, and Shopify kept sending them again: hundreds of logged errors per order. Now the app recognises such a copy by the store's secret and answers with a 200, without doing anything with it. The app's own copy does the work. Whatever has neither signature is still rejected.
  • Two webhooks, one order. A stock integration gets both orders/create and orders/paid for one order. The handling of those webhooks and a periodic sync each wrote their own stock level, so one could overwrite the other with a stale number. Now they share one lock. Whoever comes second waits, and an order is deducted only once.

A webhook is a signal, not a ledger

Even with everything above, a webhook can fail to arrive. So Shopify itself recommends a check that periodically fetches what has changed since the last time, based on updated_at. That check is the safety net. The webhook makes it fast, the check makes it right.

If your app is in the Shopify App Store, three webhooks are mandatory: customers/data_request, customers/redact and shop/redact. With them Shopify asks your app to provide or erase the data of a customer or store. You have 30 days to handle that, and a message with an invalid signature gets a 401.

What this means for you

If you have an integration between your store and an ERP, an accounting system or a warehouse, it usually runs on webhooks. Ask your developer three things:

  • Is the signature checked? Otherwise anyone who knows the address can send your integration a fake order.
  • What happens to a duplicate message? The right answer: it is recognised and skipped.
  • How does a missed message still get in? Without a periodic check, you only notice a missed order when a customer calls.

Questions about this

What is a Shopify webhook?

A message Shopify sends to your app automatically as soon as something happens in the store, such as a new order. So your app does not have to keep asking for it.

How fast does an app have to answer a webhook?

Within five seconds, with a code in the 200 range. Otherwise Shopify tries again eight times over four hours.

Can the same webhook arrive twice?

Yes, for example after a timeout. The X-Shopify-Webhook-Id header tells you it is a repeat, so you can skip it.

Is a webhook enough to miss nothing?

No. Shopify does not guarantee delivery. A periodic check through the API fetches what has changed in the meantime.