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 raadplegen, 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

Tijdigheid van gebeurtenis: Webhooks worden enkele minuten nadat een gebeurtenis plaatsvindt verzonden, waardoor u bijna realtime updates krijgt.
Consistentie van payload: De JSON-payload van een webhook komt overeen met de structuur die het overeenkomstige API-endpoint retourneert.
Automatische herkansingen: Als ChannelDock een webhook niet kan afleveren, worden er tot vijf pogingen ondernomen met oplopende vertragingen (0, 30, 60, 120 en 240 seconden). Na tien mislukte afleverpogingen wordt de webhook uit veiligheid uitgeschakeld.
Beveiliging: Elke webhook kan een eigen geheime sleutel hebben. ChannelDock gebruikt deze geheime sleutel om een digitale handtekening te berekenen zodat u de echtheid van de payload kunt verifiëren.

Een webhook instellen

Navigeer 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 Nieuwe webhook aanmaken. Er verschijnt een venster 'Webhook-configuratie'.
Vul de velden in:
- Webhook-naam: Kies een beschrijvende interne naam (bijvoorbeeld, “Orderupdates”).
- Webhook URL: Voer de URL van uw endpoint in waar ChannelDock een HTTP POST-verzoek naartoe kan sturen. Zorg dat deze URL publiek bereikbaar is en binnen 5 seconden reageert.
- Gebeurtenis om webhook te activeren: Selecteer het type 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 dit op Actief staan. Webhooks worden na 10 mislukte afleverpogingen automatisch gedeactiveerd.
- Webhook secret (optioneel maar aanbevolen): Geef uw eigen secret op of klik Genereer om een sterke secret te maken. ChannelDock gebruikt deze secret om een HMAC‑SHA256-handtekening te berekenen zodat u de payload kunt verifiëren.
Opslaan: Klik Webhook opslaan. ChannelDock slaat uw webhook op en stuurt gebeurtenissen van het type dat u geselecteerd heeft naar uw endpoint.

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 order, zending, retour of voorraadmutatie. De structuur komt overeen met de API-respons voor het overeenkomstige object.
signature – alleen aanwezig wanneer een secret is geconfigureerd. Dit is een HMAC‑SHA256-handtekening van de volledige payload, exclusief het signature-veld zelf.

De handtekening verifiëren

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

Intern gebruikt ChannelDock voor elke payload een HMAC‑SHA256-hash van de JSON-gegevens met de 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-gegevens 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 onveranderd is.

Tips voor veilige verwerking

Ken elke webhook een eigen secret toe en wissel deze regelmatig.
Gebruik een vergelijking in constante tijd (bijvoorbeeld hash_equals in PHP) om timingaanvallen te voorkomen.
Voer aanvullende controles uit op de inhoud van de payload (bijvoorbeeld verifieer dat de order bestaat) voordat u acties uitvoert.

Beste praktijken

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

HTTP‑200-respons: Laat uw endpoint 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 herkansingen). 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 monitoren en eventuele fouten te identificeren.
Payloadverwerking: Zorg ervoor dat uw endpoint grote payloads kan verwerken en binnen een redelijke tijd (≤ 5 seconden). Webhooks worden na tien mislukte afleveringen automatisch gedeactiveerd.

Dit artikel is automatisch vertaald uit het Engels.

Webhooks instellen in ChannelDock