Brandbrand
Plan een gesprek
Brandbrand
Blauwe netwerkkabels die van twee kanten in een rij poorten met groene en gele lampjes lopen

Wat Shopify-webhooks zijn, en hoe je ze betrouwbaar verwerkt

Shopify stuurt je app een bericht zodra er in je winkel iets gebeurt, maar belooft niet dat het precies één keer en op volgorde aankomt. Wat er in een webhook zit, waar het misgaat, en hoe wij ze verwerken zonder een bestelling te missen.

Shopify meldt, je app hoeft niet te vragen

Een webhook is een bericht dat Shopify naar je app stuurt zodra er in de winkel iets gebeurt. Een klant bestelt, een product krijgt een nieuwe prijs, een winkelier verwijdert de app. Elk soort gebeurtenis heet een topic, zoals orders/create of products/update. Je app abonneert zich alleen op de topics die hij nodig heeft.

Zonder webhooks moet je app steeds zelf bij Shopify vragen of er iets veranderd is. Dat heet pollen. Het kost API-budget en je loopt altijd een stap achter. Met een webhook hoor je het bijna meteen.

Meestal stuurt Shopify het bericht naar een HTTPS-adres van je app. Het kan ook naar Google Cloud Pub/Sub of Amazon EventBridge, als je app daar al draait.

Wat er in een webhook zit

Het bericht zelf is JSON, standaard met het hele object, zoals de volledige bestelling. Met include_fields beperk je dat tot de velden die je gebruikt, met filter tot de gebeurtenissen die ertoe doen. Daarnaast stuurt Shopify een reeks headers mee:

  • X-Shopify-Topic zegt om welke gebeurtenis het gaat, bijvoorbeeld orders/create.
  • X-Shopify-Shop-Domain is het myshopify.com-adres van de winkel.
  • X-Shopify-Hmac-Sha256 is de handtekening. Daarmee controleer je dat het bericht echt van Shopify komt.
  • X-Shopify-Webhook-Id is uniek per bezorging. Komt hetzelfde ID twee keer binnen, dan is het een herhaling.
  • X-Shopify-Triggered-At is het moment waarop Shopify de bezorging startte.

Drie dingen die Shopify niet belooft

Shopify is daar in de eigen documentatie duidelijk over. Een webhook komt:

  • Niet altijd precies één keer. Na een time-out of een nieuwe poging kan hetzelfde bericht opnieuw binnenkomen.
  • Niet gegarandeerd op volgorde. Ook niet binnen één topic. Een wijziging van 10:02 kan eerder binnenkomen dan die van 10:01.
  • Niet gegarandeerd. Een bericht kan ook helemaal wegblijven.

Daarbij wacht Shopify kort. Je app krijgt één seconde om de verbinding aan te nemen en vijf seconden voor het hele verzoek. Elk antwoord buiten de 200-reeks telt als fout, ook een doorverwijzing. Dan probeert Shopify het nog acht keer in vier uur.

In de app-configuratie of via de API

Je kunt je op twee manieren abonneren. In shopify.app.toml, het configuratiebestand van de app, geldt het abonnement voor elke winkel die de app installeert. Shopify raadt dat aan, tenzij topics of adressen per winkel verschillen. Via de GraphQL Admin API maak je per winkel een abonnement aan.

Het verschil merk je als het misgaat. Een abonnement via de API dat acht keer achter elkaar faalt, verwijdert Shopify, met een waarschuwing naar het noodadres van de ontwikkelaar. Een abonnement in shopify.app.toml blijft staan. En sta je twee keer op hetzelfde topic geabonneerd, dan krijg je elk bericht twee keer. Bij een van onze apps stonden na de overstap naar shopify.app.toml de oude API-abonnementen er nog. Met een eigen commando hebben we ze opgeruimd. De abonnementen uit het bestand blijven daarbij staan.

Zo verwerken wij een webhook

Omdat Shopify zo weinig belooft, doet onze app op het moment dat een webhook binnenkomt zo min mogelijk. Controleren, opslaan, antwoorden. Het echte werk komt daarna, in de wachtrij.

Van gebeurtenis tot verwerkt

  1. Er gebeurt iets in de winkel. Shopify stuurt een webhook naar de app.
  2. De app controleert de handtekening. Klopt die niet, dan antwoordt hij met 401.
  3. De app slaat het bericht op onder het webhook-ID, zet het werk in de wachtrij en antwoordt meteen.
  4. Een worker verwerkt het bericht. Een herhaling of een ouder bericht slaat hij over.
  5. Een periodieke controle haalt bij Shopify op wat er veranderd is, voor berichten die nooit kwamen.
// Controleren, opslaan, in de wachtrij zetten en meteen antwoorden.
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 een unieke kolom: een herhaling wordt niet nog eens opgeslagen.
    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

Een herhaling of een ouder bericht

De taak in de wachtrij kijkt eerst of dit webhook-ID al verwerkt is. Zo ja, dan was het een herhaling en stopt hij. De taak is uniek per webhook-ID, zodat twee kopieën niet tegelijk lopen.

Daarna de volgorde. Elke bestelling heeft een updated_at. De app bewaart die bij de eigen kopie, en schrijft alleen weg als het bericht nieuwer is. Een oud bericht dat te laat binnenkomt, overschrijft zo nooit een nieuwere stand.

public function handle(): void
{
    $delivery = WebhookDelivery::where('webhook_id', $this->webhookId)->firstOrFail();
    if ($delivery->processed_at) {
        return; // Al verwerkt: dit was een herhaling.
    }

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

    // Alleen wegschrijven als het bericht nieuwer is dan wat we al hebben.
    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

Fouten die we zelf maakten

  • Kopieën uit de winkelinstellingen. In een winkel stonden naast de app ook webhooks die met de hand waren aangemaakt in de meldingsinstellingen van de Shopify-admin. Die zijn ondertekend met een ander geheim. Onze app weigerde ze met een 401, en Shopify bleef ze opnieuw sturen: honderden foutmeldingen per bestelling. Nu herkent de app zo'n kopie aan het geheim van de winkel en antwoordt hij met een 200, zonder er iets mee te doen. Het eigen exemplaar van de app doet het werk. Wat geen van beide handtekeningen heeft, blijft geweigerd.
  • Twee webhooks, één bestelling. Een voorraadkoppeling krijgt voor één bestelling zowel orders/create als orders/paid. De afhandeling van die webhooks en een periodieke synchronisatie schreven elk hun eigen voorraadstand weg, zodat de ene de andere kon overschrijven met een verouderd getal. Nu delen ze één lock. Wie als tweede komt, wacht, en een bestelling wordt maar één keer afgeboekt.

Een webhook is een seintje, geen administratie

Ook met alles hierboven kan een webhook wegblijven. Shopify raadt daarom zelf een controle aan die periodiek ophaalt wat er sinds de vorige keer is veranderd, op basis van updated_at. Die controle is het vangnet. De webhook zorgt dat het snel gaat, de controle dat het klopt.

Staat je app in de Shopify App Store, dan zijn drie webhooks verplicht: customers/data_request, customers/redact en shop/redact. Daarmee vraagt Shopify je app om gegevens van een klant of winkel te leveren of te wissen. Je hebt 30 dagen om dat af te handelen, en een bericht met een ongeldige handtekening beantwoord je met een 401.

Wat dit voor jou betekent

Heb je een koppeling tussen je winkel en een ERP, een boekhouding of een magazijn, dan draait die meestal op webhooks. Vraag je ontwikkelaar drie dingen:

  • Wordt de handtekening gecontroleerd? Anders kan iedereen die het adres kent je koppeling een nepbestelling sturen.
  • Wat gebeurt er met een dubbel bericht? Het goede antwoord: het wordt herkend en overgeslagen.
  • Hoe komt een gemist bericht alsnog binnen? Zonder periodieke controle merk je een gemiste bestelling pas als een klant belt.

Vragen hierover

Wat is een Shopify-webhook?

Een bericht dat Shopify automatisch naar je app stuurt zodra er in de winkel iets gebeurt, zoals een nieuwe bestelling. Je app hoeft er dus niet steeds zelf naar te vragen.

Hoe snel moet een app op een webhook antwoorden?

Binnen vijf seconden, met een code in de 200-reeks. Anders probeert Shopify het nog acht keer in vier uur.

Kan dezelfde webhook twee keer binnenkomen?

Ja, bijvoorbeeld na een time-out. Met de header X-Shopify-Webhook-Id herken je een herhaling en sla je hem over.

Is een webhook genoeg om niets te missen?

Nee. Shopify garandeert de levering niet. Een periodieke controle via de API haalt op wat er in de tussentijd is veranderd.