Browse all articles

Webhooks instellen in ChannelDock

Last updated

Waarom webhooks gebruiken?

ChannelDock biedt webhooks om uw systeem direct te informeren wanneer er iets verandert in uw account. In plaats van de API periodiek te poll-en, ontvangt u automatisch een melding wanneer een bestelling wordt aangemaakt of bijgewerkt, een zending wordt aangemaakt, voorraadniveaus veranderen of een retour wordt geregistreerd. Webhooks helpen u processen te automatiseren en onnodige API-aanvragen te verminderen.

Belangrijkste kenmerken

  • Tijdstip van gebeurtenis: Webhooks worden enkele minuten na het optreden van een gebeurtenis uitgevoerd, en geven u bijna realtime-updates.
  • Consistentie van payload: De JSON-payload van een webhook komt overeen met de structuur die door het bijbehorende API-endpoint wordt teruggegeven.
  • Automatische opnieuwpogingen: Als ChannelDock een webhook niet kan afleveren, worden er tot vijf pogingen gedaan met oplopende wachttijden (0, 30, 60, 120 en 240 seconden). Na tien mislukte afleverpogingen wordt de webhook uit veiligheidsoverwegingen uitgeschakeld.
  • Beveiliging: Elke webhook kan een eigen geheime sleutel hebben. Als er een secret is ingesteld, ondertekent ChannelDock elke aflevering met een HMAC-SHA256-handtekening in de X-Channeldock-Signature-header, zodat u kunt verifiëren dat een verzoek echt van ChannelDock komt.

Een webhook instellen

  1. Naar de instellingen gaan: Log in op ChannelDock en ga naar Instellingen → API & Webhooks. U ziet twee secties: API-sleutels en Webhooks.

  2. Een nieuwe webhook aanmaken: Klik op Maak nieuwe webhook. Er verschijnt een venster ‘Webhookconfiguratie’.

  3. Vul de velden in:

    • Webhooknaam: Kies een beschrijvende interne naam (bijvoorbeeld ‘Order updates’).
    • Webhook-URL: Voer de URL in van uw endpoint waar ChannelDock een HTTP POST-verzoek naartoe kan sturen. Zorg dat deze URL publiek bereikbaar is en binnen 5 seconden reageert.
    • Evenement dat webhook activeert: Selecteer het type evenement waarvoor u meldingen wilt ontvangen. Mogelijke evenementen zijn order.created, order.updated, order.status.changed, order.picking, order.picked, order.deleted, shipment.created, stock.updated, return.created, return.handled en return.product.updated.
    • Status: Laat deze ingesteld op Active. Webhooks worden na 10 mislukte afleverpogingen automatisch gedeactiveerd.
    • Webhook secret (optioneel maar aanbevolen): Geef uw eigen secret op of klik op Generate om een sterke secret te maken. ChannelDock gebruikt deze secret om elke aflevering te ondertekenen, zodat u kunt verifiëren dat het verzoek van ChannelDock komt en onderweg niet is gewijzigd.

  4. Opslaan: Klik op Webhook opslaan. ChannelDock slaat uw webhook op en zal evenementen van het door u geselecteerde type naar uw endpoint sturen.

Structuur van de payload en evenementen

Wanneer het gekozen evenement plaatsvindt, stuurt ChannelDock een JSON-payload naar uw endpoint. De payload bevat minstens de volgende velden:

{   
  "event": "order.created",  
  "payload": {   
    ...  
  },  
  "signature": "<hash>" (verouderd, zie hieronder)  
}
  • event – het evenement waarvoor de webhook is geconfigureerd (bijvoorbeeld order.created).
  • payload – bevat details van de bestelling, zending, retour of voorraadmutatie. De structuur komt overeen met de API-respons voor het betreffende object.
  • signature – alleen aanwezig wanneer er een secret is geconfigureerd. Dit is de oude handtekening en is verouderd; verifieer in plaats daarvan de X-Channeldock-Signature-header.

De handtekening verifiëren

Uw webhook-URL moet publiek bereikbaar zijn, en het verzoek bevat geen ander bewijs van wie het verstuurd heeft — geen API-sleutel, geen wachtwoord. Alles wat die URL bereikt, ziet er voor uw endpoint dus uit als een echte ChannelDock-aflevering: een URL die is uitgelekt via een logbestand, een proxy of een supportticket, of een eerdere aflevering die iemand heeft opgevangen en opnieuw verstuurd. Handelt u zonder controle op de inhoud, dan kan een nagemaakte stock.updated uw voorraad op nul zetten, of een nagemaakte order.updated een bestelling in uw eigen systeem als verzonden markeren.

De handtekening is dat ontbrekende bewijs. Alleen u en ChannelDock kennen de secret, dus alleen u beiden kunnen een waarde produceren die bij de aflevering hoort die u voor u heeft.

Zodra u een webhook secret instelt, komt elke aflevering voor die webhook binnen met een extra HTTP-header:

X-Channeldock-Signature: sha256=8b415f2c0cd241a21109e007942b6ce43cbfcf97f7b2d7829084258c0ae0a66f

Die waarde is een HMAC-SHA256-hash van de request body, berekend met uw secret als sleutel. U berekent dezelfde hash aan uw kant en controleert of de twee identiek zijn. Is er geen secret ingesteld, dan wordt de header niet verzonden.

De handtekening verifiëren in uw applicatie

  1. Lees de ruwe body. Neem de request body als tekst of bytes, vóórdat de JSON wordt geparseerd. De meeste frameworks parseren de JSON en gooien de originele tekst weg, dus vraag die expliciet op: php://input in PHP, $request->getContent() in Laravel, request.get_data() in Flask, request.body in Django, request.raw_post in Rails, of express.json({ verify: (req, res, buf) => { req.rawBody = buf } }) in Express.
  2. Lees de header. Neem X-Channeldock-Signature en haal het sha256=-voorvoegsel eraf. Zoek de header op zonder op hoofdletters te letten — afhankelijk van de verbinding komt hij binnen als x-channeldock-signature.
  3. Bereken uw eigen hash. Een HMAC-SHA256 van de ruwe body met uw webhook secret als sleutel, geschreven als hexadecimaal. In PHP is dat hash_hmac('sha256', $raw, $secret).
  4. Vergelijk met een constant-time functie zoals hash_equals. Zijn de twee identiek, dan is de aflevering echt en kunt u die verwerken. Zo niet, geef HTTP 401 terug en negeer de body. Parseer de JSON pas nadat deze stap is gelukt.

Belangrijk: hash de body precies zoals u die ontvangen heeft. Een handtekening is een hash van bytes, niet van de betekenis van de JSON. Parseer de JSON dus niet om die daarna weer naar tekst om te zetten en te hashen. Twee talen kunnen JSON schrijven die precies hetzelfde betekent maar niet dezelfde tekst is: PHP schrijft een schuine streep als c\/o waar Node.js en Python c/o schrijven. Dat leest terug als identieke gegevens, maar levert een volledig andere hash op. Verwijder ook het signature-veld niet voordat u hasht — het hoort bij de body die is ondertekend.

Het verouderde signature-veld

Voordat de header bestond, zette ChannelDock een signature-veld in de body zelf. Dat veld wordt nog steeds ongewijzigd verzonden, dus bestaande koppelingen blijven werken, maar het is verouderd. Verifiëren betekent namelijk dat u het veld verwijdert en de resterende JSON opnieuw als tekst opbouwt, precies zoals PHP dat doet, inclusief de gewoonte van PHP om / als \/ te schrijven. In een andere taal is dat vrijwel niet goed te krijgen.

Bouw nieuwe koppelingen op de header. Verifieert u het veld nu al, dan breekt er niets: beide worden bij elke aflevering verzonden, dus u kunt overstappen wanneer het u uitkomt. De twee waarden zijn nooit gelijk, omdat ze over andere gegevens gaan — vergelijk ze dus nooit met elkaar.

Tips voor veilige verwerking

  • Ken elke webhook een eigen secret toe en roteer deze regelmatig.
  • Gebruik een constant-time vergelijkingsfunctie (bijvoorbeeld hash_equals in PHP of crypto.timingSafeEqual in Node.js) om timing-aanvallen te voorkomen.
  • Verifieer de handtekening voordat u iets doet met de inhoud van de payload.
  • Voer aanvullende controles uit op de inhoud van de payload (bijvoorbeeld verifieer dat de bestelling bestaat) voordat u acties uitvoert.

Beste praktijken

ChannelDock raadt de volgende werkwijzen aan om webhooks veilig en betrouwbaar te verwerken:

  • HTTP‑200-antwoord: Laat uw endpoint zo snel mogelijk een HTTP 200 OK teruggeven zodra de payload succesvol is ontvangen. Anders ziet ChannelDock de poging als mislukt en probeert het opnieuw.
  • Idempotentie: Webhookberichten kunnen soms twee keer worden verzonden (bijvoorbeeld door netwerkproblemen of opnieuwpogingen). Zorg dat uw verwerkingslogica idempotent is zodat dubbele berichten geen dubbel werk veroorzaken.
  • Monitoring: Gebruik het ChannelDock-dashboard om de status van uw webhooks te monitoren en eventuele fouten te identificeren.
  • Omgang met payloads: Zorg dat uw endpoint grote payloads aankan en binnen een redelijke tijd (≤ 5 seconden) reageert. Webhooks worden na tien mislukte afleveringen automatisch gedeactiveerd.

Dit artikel is automatisch vertaald uit het Engels.

Was this helpful?