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. ChannelDock gebruikt deze sleutel om een digitale handtekening te berekenen zodat u de authenticiteit van de payload kunt verifiëren.

Een webhook instellen

Naar de instellingen gaan: Log in op ChannelDock en ga naar Instellingen → API & Webhooks. U ziet twee secties: API-sleutels en Webhooks.
Een nieuwe webhook aanmaken: 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 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.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 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 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>" (Optioneel maar aanbevolen)
}

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 een HMAC‑SHA256-handtekening van de volledige payload, behalve het signature-veld zelf.

De handtekening verifiëren

Het is belangrijk te verifiëren dat de webhook door ChannelDock is verzonden en dat de payload niet is gewijzigd. Dit doet u door de door ChannelDock meegeleverde handtekening te vergelijken met uw eigen berekening.

Intern gebruikt ChannelDock voor iedere 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 secret key samen met de HMAC-SHA256-hashmethode om een nieuwe handtekening te maken. Voer dit uit op de JSON-gegevens die u hebt ontvangen (zonder het signature-veld).
Vergelijk de hashes: Als de door u berekende hash precies overeenkomt met de ontvangen handtekening, kunt u erop vertrouwen dat de payload authentiek en niet gewijzigd is.

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) om timing-aanvallen te voorkomen.
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.

Webhooks instellen in ChannelDock