Veloyd logo

Webhooks instellen

Met een webhook krijgt je eigen systeem, bijvoorbeeld een webshop of WMS, direct een bericht als een rit of zending verandert, zoals bij een nieuwe status. Je stelt webhooks in het klantportaal in bij Instellingen > Koppelingen > API, onder Webhooks.

Webhooks werken ook zonder API key. Staat de API toegang van je account op Uit, dan zie je de webhooks niet en worden er geen webhooks verstuurd. Neem dan contact op met je vervoerder. Meer over keys en API toegang lees je in Instellingen en koppelingen.

Een webhook toevoegen #

  1. Ga naar Instellingen > Koppelingen > API.
  2. Klik onder Webhooks op Webhook toevoegen. Je kunt maximaal 10 webhooks hebben. Zijn het er 10, dan staat de knop er niet meer.
  3. Vul de gegevens van de webhook in. Die staan hieronder per onderdeel uitgelegd.
  4. Klik op Opslaan. De webhook is direct opgeslagen, je hoeft niet op de knop Opslaan van de pagina te klikken.

De gegevens van een webhook #

  • Naam — verplicht, met maximaal 100 tekens.
  • Voor — kies Ritten of Zendingen. Wijzig je dit, dan krijgt de webhook de standaard gebeurtenissen van die soort.
  • URL — het adres waar de berichten naartoe gaan. Een URL begint met https:// en moet vanaf internet bereikbaar zijn. Een adres binnen een netwerk, zoals localhost of een privé IP-adres, kan niet. Je gebruikt een URL maar één keer per soort. Laat je het veld leeg, dan is dit de webhook voor de URL uit de API. Dat staat verderop uitgelegd.
  • Actief — met deze schakelaar zet je de webhook aan of uit. Een webhook die uit staat, krijgt in de lijst het label Uit en stuurt geen berichten.

In de lijst staat per webhook de soort, de naam, de URL en het aantal gebeurtenissen. Klik op een regel om de webhook te bewerken.

Gebeurtenissen #

Onder Gebeurtenissen kies je bij welke gebeurtenissen de webhook een bericht krijgt. Kies minstens één gebeurtenis. Een nieuwe webhook krijgt standaard alle gebeurtenissen, behalve ETA gewijzigd.

Bij een webhook voor Ritten kies je uit:

  • Aangemaakt
  • Gewijzigd
  • Ingepland
  • Status gewijzigd
  • Opgehaald
  • Niet opgehaald
  • Bezorgd
  • Niet bezorgd
  • Geannuleerd
  • ETA gewijzigd
  • Opmerking

Bij een webhook voor Zendingen kies je uit:

  • Aangemaakt
  • Bevestigd
  • Opgehaald
  • Onderweg
  • Manco
  • Op afhaalpunt
  • Bezorgd
  • Retour
  • Geannuleerd
  • Status gewijzigd

Beveiliging #

Onder Beveiliging stel je in hoe jouw systeem herkent dat een webhook van Veloyd komt. Een webhook stuurt nooit een API key mee. Je kunt twee dingen gebruiken: een HMAC key en eigen headers.

Een nieuwe webhook krijgt automatisch een HMAC key. De key is verborgen. Met de icoontjes ernaast toon je de key, kopieer je hem, maak je een nieuwe key aan met Nieuwe HMAC key of verwijder je hem. Heeft de webhook geen HMAC key meer, dan klik je op Nieuwe HMAC key om er een aan te maken.

Elke webhook met een HMAC key heeft de headers Timestamp, Content-MD5 en Signature. De Timestamp is het tijdstip in ISO 8601 en UTC. Zo controleer je de handtekening. Klik in het klantportaal op Hoe controleer je de HMAC handtekening? voor dezelfde uitleg.

  1. Bereken de MD5 hash van de body zoals je die ontvangt, voordat je hem omzet, en codeer die in base64. Die moet gelijk zijn aan Content-MD5.
  2. Maak het bericht: POST, de Timestamp, het pad van je webhook URL zonder domein en zonder query, en de Content-MD5. Zet elk onderdeel op een eigen regel, gescheiden door \n, zonder regel aan het eind.
  3. Bereken de HMAC-SHA256 van dat bericht met je HMAC key en codeer die in base64. Is die gelijk aan Signature, dan komt de webhook van Veloyd en is hij onderweg niet gewijzigd.
  4. Weiger een webhook met een Timestamp van meer dan een paar minuten geleden. Zo kan niemand een onderschepte webhook later opnieuw versturen. Elke nieuwe poging krijgt een nieuwe Timestamp en Signature.
  5. Vergelijk Signature met een vergelijking die altijd even lang duurt, bijvoorbeeld crypto.timingSafeEqual of hash_equals.

Je kunt ook eigen headers meesturen, bijvoorbeeld Authorization met een eigen token. Klik op Header toevoegen en vul de Header naam en de Header waarde in. Je kunt maximaal 5 headers toevoegen. Met het prullenbak-icoon verwijder je een header. Een headernaam gebruik je maar één keer en kan niet een van deze namen zijn: Content-Type, Content-Length, Accept, Host, Timestamp, Content-MD5, Signature, X-Webhook-Event en X-Webhook-Id.

Wat een webhook bevat #

Elke webhook heeft de header X-Webhook-Event met de gebeurtenis en de header X-Webhook-Id met een uniek id. Aan dat id herken je dubbele berichten. Het bericht zelf is JSON.

Een webhook is geslaagd bij een antwoord van 200 tot en met 299. Mislukt een webhook, dan probeert Veloyd hem ongeveer een dag lang opnieuw. Elke nieuwe poging krijgt een nieuwe Timestamp en Signature.

Een webhook testen #

Bij een webhook met een opgeslagen URL staat een verstuur-icoon. Met dat icoon stuur je een testwebhook naar de opgeslagen URL. Dat werkt ook als de webhook uit staat. Onder de webhook verschijnt het antwoord van jouw systeem, bijvoorbeeld dat de testwebhook is verstuurd en met welk antwoord. Is het antwoord geen 200 tot en met 299, dan staat er een waarschuwing bij dat de webhook pas geslaagd is bij zo’n antwoord. Kan de testwebhook niet worden verstuurd, dan zie je de reden.

Webhook URL uit de API #

Je kunt een rit of zending via de API aanmaken met een eigen webhook URL. Welke instellingen die URL gebruikt, hangt af van je webhooks van dezelfde soort:

  • Heeft een webhook dezelfde URL, dan gelden de instellingen van die webhook.
  • Anders gelden de instellingen van de webhook zonder URL. Die heet in de lijst Webhook URL uit de API. Je kunt per soort één webhook zonder URL hebben.
  • Is er ook geen webhook zonder URL, dan krijgt de URL alle gebeurtenissen behalve ETA gewijzigd, zonder HMAC key en zonder eigen headers.

Staat de webhook zonder URL uit, dan krijgt een URL uit de API geen berichten. Een URL uit de API die geen geldige URL is, of die naar een adres binnen een netwerk wijst, wordt overgeslagen. De andere webhooks worden gewoon verstuurd.

Een webhook verwijderen #

Klik op de regel van de webhook en dan op Verwijder webhook. Bevestig het verwijderen. De URL krijgt daarna geen webhooks meer.