Waarom webhooks gebruiken?

ChannelDock biedt webhooks om uw systeem onmiddellijk te informeren wanneer er iets verandert in uw account. In plaats van periodiek de API te pollen, 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 nadat een gebeurtenis zich voordoet verzonden, waardoor u bijna realtime-updates ontvangt.
Consistentie van payload: De JSON-payload van een webhook komt overeen met de structuur die door het overeenkomstige API-endpoint wordt geretourneerd.
Automatische herhalingspogingen: Als ChannelDock een webhook niet kan afleveren, worden tot vijf pogingen gedaan met toenemende tussenpozen (0, 30, 60, 120 en 240 seconden). Na tien mislukte afleverpogingen wordt de webhook uit veiligheidsoverwegingen gedeactiveerd.
Beveiliging: Elke webhook kan zijn eigen geheime sleutel hebben. ChannelDock gebruikt deze geheime sleutel om een digitale handtekening te berekenen zodat u de authenticiteit van de payload kunt verifiëren.

Een webhook instellen

Ga naar de instellingen: Meld u aan bij ChannelDock en ga naar Instellingen → API & Webhooks. U ziet twee secties: API-sleutels en Webhooks.
Maak een nieuwe webhook aan: Klik op Maak nieuwe webhook aan. Er verschijnt een venster “Webhookconfiguratie”.
Vul de velden in:
- Naam van webhook: Kies een beschrijvende interne naam (bijvoorbeeld “Bestelupdates”).
- Webhook-URL: Voer de URL van uw endpoint in waar ChannelDock een HTTP POST-verzoek naartoe kan sturen. Zorg ervoor dat deze URL publiek bereikbaar is en binnen 5 seconden reageert.
- Gebeurtenis die de webhook activeert: Kies het soort gebeurtenis waarvoor u meldingen wilt ontvangen. Mogelijke gebeurtenissen zijn order.created, order.updated, order.status.changed, order.deleted, shipment.created, stock.updated, return.created, return.handled en return.product.updated.
- Status: Laat deze op Actief staan. Webhooks worden automatisch gedeactiveerd na 10 mislukte afleverpogingen.
- Webhook-geheim (optioneel maar aanbevolen): Geef uw eigen geheim op of klik op Genereer om een sterk geheim te maken. ChannelDock gebruikt dit geheim om een HMAC‑SHA256-hashhandtekening te berekenen zodat u de payload kunt verifiëren.
Opslaan: Klik op Webhook opslaan. ChannelDock slaat uw webhook op en zal gebeurtenissen van het door u geselecteerde type naar uw endpoint sturen.

Structuur van de payload en gebeurtenissen

Wanneer een gekozen gebeurtenis plaatsvindt, stuurt ChannelDock een JSON-payload naar uw endpoint. De payload bevat ten minste de volgende velden:

{ 
  "event": "order.created",
  "payload": { 
    ...
  },
  "signature": "<hash>" (Optioneel maar aanbevolen)
}

event – de gebeurtenis 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 overeenkomstige object.
signature – alleen aanwezig wanneer er een geheim is geconfigureerd. Dit is een HMAC‑SHA256-handtekening van de volledige payload, behalve het handtekeningveld zelf.

Het verifiëren van de handtekening

Het is belangrijk om te controleren dat de webhook door ChannelDock is verzonden en dat de payload niet is gemanipuleerd. Dit doet u door de handtekening die ChannelDock heeft meegegeven te vergelijken met uw eigen berekening.

Intern gebruikt ChannelDock voor elke payload een HMAC‑SHA256-hash die wordt berekend met het door u geconfigureerde geheim. De resulterende hash wordt toegevoegd als het signature-veld in de payload.

Het verifiëren van de handtekening in uw applicatie

Ontvang de webhook: Parseer de JSON en sla tijdelijk de waarde van het signature-veld op. Verwijder het signature-veld uit de payload voordat u de hash berekent.
Genereer een hash: Gebruik uw geheime sleutel samen met de HMAC-SHA256-hashmethode om een nieuwe handtekening te maken. Voer dit uit op de JSON-gegevens die u ontving (zonder het signature-veld).
Vergelijk de hashes: Als de hash die u berekent precies overeenkomt met de ontvangen handtekening, kunt u erop vertrouwen dat de payload authentiek en ongewijzigd is.

Tips voor veilige verwerking

Ken elke webhook een eigen geheim toe en roter dit regelmatig.
Gebruik een vergelijkingsfunctie met constante tijd (bijvoorbeeld hash_equals in PHP) om timing-aanvallen te voorkomen.
Voer aanvullende controles uit op de inhoud van de payload (controleer bijvoorbeeld of de bestelling bestaat) voordat u acties uitvoert.

Aanbevolen werkwijzen

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

HTTP‑200-respons: Laat uw endpoint een HTTP 200 OK retourneren 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 herhalingen). 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 detecteren.
Payloadverwerking: Zorg dat uw endpoint grote payloads kan verwerken en binnen een redelijke tijd (≤ 5 seconden) reageert. Webhooks worden automatisch gedeactiveerd na tien mislukte afleverpogingen.

Dit artikel is automatisch vertaald uit het Engels.

Webhooks instellen in ChannelDock