Webhooks in GoedGepickt

Updated by Stan

In deze handleiding leggen we uit hoe webhooks werken in GoedGepickt.

Wat zijn webhooks?

Met webhooks is het mogelijk om vanuit GoedGepickt notificaties te krijgen op het moment dat er een bepaalde actie plaatsvindt in GoedGepickt. Deze notificaties worden gestuurd naar een door jou ingestelde URL met daarin data, zodat de URL deze data weer kan verwerken.

Het voordeel hiervan is dat jouw systeem realtime op de hoogte wordt gebracht van deze acties. Hierdoor hoef je dus niet periodiek de API aan te roepen om data te ontvangen (periodiek data opvragen via polling), maar brengen wij jou op de hoogte van wijzigingen.

Voor het gebruik & verwerken van de data uit webhooks is technische kennis vereist. Schakel hiervoor een softwareontwikkelaar in.

Hoe maak je webhooks aan?

Je kan webhooks aanmaken via Instellingen -> Webhooks. Je stelt per webhook een URL in (de target URL) en je kiest op welk event je je aanmeldt.

Er zijn twee niveaus:

  • Algemene instellingen: de webhook geldt voor je hele account. Hier vind je alle events, dus ook rapporten, inkoopbestellingen en retouren.
  • Per webshop: de webhook geldt alleen voor die webshop. Hier kies je uit de events voor producten, bestellingen en zendingen.

Werk je met fulfilment, dan kan je een webhook beperken tot een fulfilmentklant. Laat je dat veld leeg, dan geldt de webhook voor al je klanten. In de payload sturen we dan fulfilmentCustomerUuid mee.

Na het toevoegen, zie je een validatiesleutel. Dit is een sleutel waarmee je kan controleren of de data volledig is en of er niet mee is geknoeid.

Je kan webhooks ook via de API aanmaken en verwijderen. De API gebruikt eventnamen met een punt, zoals product.stockChanged. Producten dearchiveren, de voorraad van samengestelde producten en de retour-events zet je alleen via de instellingenpagina aan.

Welke webhooks kan je aanzetten?

Hieronder staan alle events, met de waarde van het veld event zoals die in de payload staat. Daar filter je in je eigen code op. Bij de meeste events sturen we hetzelfde object mee als de API teruggeeft, zodat je meteen verder kan zonder extra call.

Producten

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Product aangemaakt

productCreated

Een nieuw product, of je het nu handmatig aanmaakt, via Excel importeert, via de API stuurt of vanuit een webshopkoppeling binnenhaalt. Payload: het volledige product.

Product aangepast

productChanged

Productgegevens wijzigen. Zit het product in een samengesteld product, dan sturen we ook een wijziging voor het bovenliggende product. Payload: het volledige product.

Product gearchiveerd

productArchived

Een product archiveren. Payload: alleen uuid en sku.

Product gedearchiveerd

productRestored

Een gearchiveerd product terugzetten. Payload: het volledige product.

Voorraad aangepast

stockUpdated

Elke voorraadmutatie: picken, ontvangen, tellen, corrigeren of een retour. Payload: newStock (de vrije voorraad inclusief de stockbuffer van die webshop), mutation, reason, allowBackorders en deliveryPeriod. Bij een buffer ook newStockWithoutBuffer, bij batch- of THT-voorraad ook batches.

Voorraad verplaatst

productStockMoved

Voorraad van de ene picklocatie naar de andere verplaatsen. Payload: items met per regel het product, de oude locatie, de nieuwe locatie en het aantal.

Samengesteld product voorraad aangepast

compoundProductStockUpdated

De vrije voorraad van een samengesteld product verandert doordat een onderdeel wijzigt. Payload: de voorraad plus childStocks per onderdeel.

Bestellingen

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Bestelling aangemaakt

orderCreated

Een nieuwe bestelling. Staat de bestelling nog op processing, dan wachten we tot de verzendmethode bekend is, maximaal ongeveer 2,5 minuut. Payload: de volledige bestelling.

Bestelling aangepast

orderChanged

Een wijziging in de bestelling, de regels, de adressen of de tags, ook vanuit de API of het fulfilmentportaal. Payload: de volledige bestelling.

Bestelstatus aangepast

orderStatusChanged

Elke statuswijziging. Payload: alleen newStatus, orderNumber en orderUuid. Wil je meer weten, haal de bestelling dan op via de API.

Bestelling afgerond

orderCompleted

De status wordt completed. Je krijgt dan ook Bestelstatus aangepast, als je die aan hebt staan. Payload: orderNumber en orderUuid.

Bestelling gearchiveerd

orderArchived

Een bestelling archiveren. Payload: alleen uuid en het bestelnummer.

Bestelling als aandacht vereist gemarkeerd

attentionNeeded

Het vlaggetje aandacht vereist gaat aan, bijvoorbeeld bij een adres- of voorraadprobleem. Payload: de volledige bestelling.

Zendingen

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Zending aangemaakt

shipmentCreated

Er is een zending aangemaakt, ook als het om een retourzending gaat die je zelf aanmaakt. Payload: de zending met track-en-tracecode en -link, vervoerder, methode, gewicht, verpakkingsmateriaal, de zendingregels, de gekoppelde bestelling en isReturnShipment.

Rapporten

Alleen beschikbaar onder Algemene instellingen.

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Rapport gegenereerd

report_generated

Een rapport is klaar. Payload: het rapport. Let op: dit is het enige event met een underscore in de waarde.

Inkoopbestellingen

Alleen beschikbaar onder Algemene instellingen.

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Inkoopbestelling aangemaakt

purchaseOrderCreated

Een nieuwe inkoopbestelling. Payload: de volledige inkoopbestelling.

Inkoopbestelling aangepast

purchaseOrderChanged

Een wijziging die niet de status is. Wijzigt de status, dan krijg je alleen het status-event en niet ook dit event. Payload: de volledige inkoopbestelling.

Inkoopbestelling status aangepast

purchaseOrderStatusUpdated

De status van de inkoopbestelling wijzigt. Payload: de volledige inkoopbestelling.

Inkoopbestelling verwijderd

purchaseOrderDeleted

Een inkoopbestelling verwijderen. Payload: de volledige inkoopbestelling.

Retouren

Alleen beschikbaar onder Algemene instellingen.

In de app

Event in de payload

Wanneer wij sturen en wat je krijgt

Retour aangemaakt

return_returnCreated

Een nieuwe retour. Payload: de volledige retour met de gekoppelde bestellingen.

Retour aangepast

return_returnChanged

Elke wijziging aan de retour. Payload: de volledige retour.

Retour afgerond

return_returnCompleted

De retour krijgt de status afgerond. Je krijgt dan ook Retour aangepast. Payload: de volledige retour.

Retour gearchiveerd

return_returnArchived

Een retour verwijderen of archiveren. Payload: de volledige retour.

Wat wij versturen

  • Een POST met een JSON-body naar jouw target URL.
  • De headers Content-Type: application/json, User-Agent: GoedGepickt/Webhook en Signature.
  • Gebruik je https, dan moet je certificaat geldig zijn. Een self-signed certificaat mislukt.
  • We sturen alleen webhooks die op actief staan. Zet je een webhook uit, dan stoppen ook de herhaalpogingen die nog in de wachtrij staan.

Logboek van webhooks

Via Instellingen -> Webhooks -> Webhook logs (bovenin je scherm) kan je de pagina vinden waarin alle webhooks worden geregistreerd.

In GoedGepickt houden we een logboek bij met alle webhooks die verstuurd zijn in jouw account. Hierin zie je welk event er is uitgevoerd, op welke datum & tijd, welke HTTP statuscode wij als reactie terugkregen, het poging-nummer en de payload die met de webhook meegestuurd is.

Door op het item te klikken, krijg je meer informatie te zien, zoals welke URL er is aangeroepen en wat jouw omgeving als response aan ons teruggaf. Bijvoorbeeld wanneer jouw systeem een foutmelding teruggeeft.

Twee dingen om te weten: de response wordt na 245 tekens afgekapt, dus log aan jouw kant mee als je het volledige antwoord wilt zien. En we bewaren de logs een maand, daarna ruimen we ze automatisch op.

Gemiste webhooks

We verwachten binnen 10 seconden een reactie met statuscode 200. Komt die er niet, dan breken we het verzoek af en zie je in de logs statuscode 0.

Is de statuscode niet gelijk aan 200, dan proberen we het opnieuw. In totaal doen we 9 pogingen, met deze wachttijden ertussen:

  • 10 seconden na de eerste poging
  • 100 seconden na de tweede
  • 1.000 seconden na de derde
  • 10.000 seconden (bijna 3 uur) na de vierde
  • daarna 1 dag na elke volgende poging

De laatste poging valt dus ruim 4 dagen na de eerste. Ligt jouw endpoint een dag uit de lucht, dan haal je de webhook daarna alsnog binnen.

Na de zevende mislukte poging sturen we de melding "Actie vereist voor falende webhook" naar de gebruikers in je account. Daarna volgen nog twee pogingen, een per dag. Mislukken die ook, dan zetten we de webhook automatisch op inactief. Na het oplossen van het probleem zet je hem zelf weer aan via Instellingen -> Webhooks.

Webhooks valideren

Je wilt natuurlijk graag zeker weten dat de webhooks die je ontvangt, ook echt vanuit GoedGepickt komen. Vergelijk daarvoor de header Signature met de volgende berekening (voorbeeld in PHP):

$computedSignature = hash_hmac('sha256', $request->getContent(), $webhookSecret);

In $webhookSecret plaats je de webhook-secret zoals die in GoedGepickt wordt weergegeven. Als $computedSignature gelijk is aan de signature header, dan is de webhook valide.

Reken over de ruwe body, niet over een opnieuw samengestelde JSON. Anders wijkt de hash af.

Tip

Als je wilt gaan testen hoe (snel) de webhooks naar jouw omgeving worden gestuurd, kan je online tools gebruiken als:

Let op: er is geen testknop. Een webhook vuurt op een echte actie in je account. Pas dus zelf een voorraad aan of maak een bestelling, dan zie je het verzoek binnenkomen.

Vragen?

Nu weet je wat webhooks zijn in GoedGepickt. Zijn er toch nog onduidelijkheden, heb je andere vragen of ideeën? Neem dan contact met ons op, wij helpen je graag!

Voor het gebruik & verwerken van de data uit webhooks is technische kennis vereist. Schakel hiervoor een softwareontwikkelaar in.

Hoe vond je dit artikel?