Waarom webhooks gebruiken?

ChannelDock biedt webhooks om uw systeem direct te informeren wanneer er iets verandert in uw account. In plaats van periodiek de API te polsen, ontvangt u automatisch een melding wanneer een order 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 verzonden, zodat u bijna realtime updates ontvangt.
Consistente payload: De JSON-payload van een webhook komt overeen met de structuur die door het bijbehorende API-endpoint wordt geretourneerd.
Automatische opnieuwpogingen: Als ChannelDock een webhook niet kan afleveren, worden er tot vijf pogingen gedaan met toenemende vertragingen (0, 30, 60, 120 en 240 seconden). Na tien mislukte afleveringen wordt de webhook uit veiligheidsoverwegingen uitgeschakeld.
Beveiliging: Elke webhook kan zijn eigen geheime sleutel hebben. ChannelDock gebruikt deze sleutel om een digitale handtekening te berekenen zodat u de authenticiteit van de payload kunt verifiëren.

Een webhook instellen

Ga naar de instellingen: Log in op 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. Er verschijnt een venster “Webhookconfiguratie”.
Vul de velden in:
- Webhooknaam: Kies een beschrijvende interne naam (bijvoorbeeld “Order-updates”).
- Webhook‑URL: Voer de URL van uw endpoint in waar ChannelDock een HTTP POST-request naartoe kan sturen. Zorg dat deze URL publiek bereikbaar is en binnen 5 seconden reageert.
- Gebeurtenis die de webhook activeert: Selecteer het type gebeurtenis waarvoor u meldingen wilt ontvangen. Mogelijke evenementen zijn onder andere order.created, order.updated, order.status.changed, order.deleted, shipment.created, stock.updated, return.created, return.handled en return.product.updated.
- Status: Laat dit ingesteld op Actief. Webhooks worden automatisch gedeactiveerd na 10 mislukte afleverpogingen.
- Webhooksecret (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 evenementen

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

{ 
  "event": "order.created",
  "payload": { 
    ...
  },
  "signature": "<hash>" (Optional but recommended)
}

event – de gebeurtenis waarvoor de webhook is geconfigureerd (bijvoorbeeld order.created).
payload – bevat details van de order, zending, retour of voorraadmutatie. De structuur komt overeen met de API-respons voor het betreffende object.
signature – alleen aanwezig wanneer een secret is geconfigureerd. Dit is een HMAC‑SHA256-handtekening van de volledige payload, met uitzondering van het signature-veld zelf.

De handtekening verifiëren

Het is belangrijk te zorgen dat de webhook door ChannelDock is verzonden en dat de payload niet is aangepast. U doet dit door de door ChannelDock verstrekte handtekening te vergelijken met uw eigen berekening.

ChannelDock ondertekent intern elke payload door een HMAC‑SHA256-hash van de JSON-data te berekenen met het door u geconfigureerde secret. De resulterende hash wordt toegevoegd als het signature-veld in de payload.

De handtekening verifiëren 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-data die u heeft ontvangen (zonder het signature-veld).
Vergelijk de hashes: Als de door u berekende hash exact overeenkomt met de ontvangen handtekening, kunt u erop vertrouwen dat de payload authentiek en ongewijzigd is.

Tips voor veilige verwerking

Wijs elke webhook een eigen secret toe en roteer deze regelmatig.
Gebruik een constant‑time vergelijkingfunctie (bijvoorbeeld hash_equals in PHP) om timingaanvallen te voorkomen.
Voer extra controles uit op de inhoud van de payload (bijvoorbeeld verifieer dat de order 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 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 dubbel worden verzonden (bijvoorbeeld door netwerkproblemen of opnieuwpogingen). Zorg dat uw verwerkingslogica idempotent is, zodat dubbele berichten niet tot dubbel werk leiden.
Monitoring: Gebruik het ChannelDock-dashboard om de status van uw webhooks te bewaken en eventuele fouten te identificeren.
Payloadverwerking: Zorg ervoor dat uw endpoint grote payloads kan verwerken en binnen een redelijke tijd (≤ 5 seconden) reageert. Webhooks worden automatisch uitgeschakeld na tien mislukte afleverpogingen.

Dit artikel is automatisch vertaald uit het Engels.

Webhooks instellen in ChannelDock