Overslaan en naar hoofdcontent gaan
Terug naar boven

Wat zijn webhooks en hoe gebruik je deze in combinatie met Sendcloud?

Joan
  • Bijgewerkt

Doel: leer de basis over webhooks en hoe je ze kunt configureren in je Sendcloud panel.

Om webhooks te kunnen gebruiken moet je via een API verbinding maken met Sendcloud. Voor meer informatie over het verbinden met onze API, verwijzen we je naar onze API Documentatie.

Voor meer informatie over Sendcloud webhooks, zie de Webhooks secties in onze API-documentatie. 

Voor integratiespecifieke webhook-ondersteuning bekijk ons artikel: Verbetering van Webhook-beveiliging en Integratieondersteuning. Het behandelt de webhook-instelling voor verschillende integraties en beste praktijken voor het beveiligen van je webhooks.

Wat zijn webhooks?

Webhooks maken het mogelijk voor applicaties om met elkaar te communiceren in 'real time'. Een andere manier voor applicaties om te communiceren is via een API. In tegenstelling tot een API die werkt met polling, ontvangt een webhook gegevens zodra de applicaties het afhandelt. Er hoeft geen request te worden gedaan, omdat het een automatisch proces is. Daarom hoef je je geen zorgen te maken over een vertraging in de communicatie.

API: een API haalt periodiek gegevens uit de applicatie door een request te doen.

Webhook: een webhook pulled geen gegevens uit de applicatie, maar krijgt gegevens uit de applicatie gepusht zodra het incident zich voordoet.

Voorbeeld: tracking updates ontvangen van Sendcloud

(Zie onderstaande afbeeldingen ter referentie)

  1. Als je tracking updates ontvangt via de API gaat het als volgt:
    Je applicatie probeert via interval trackinggegevens uit Sendcloud te pullen. Dat doet het zelfs als er geen nieuwe gegevens beschikbaar zijn.
  2. Wanneer je tracking updates wilt ontvangen via een webhook gaat het als volgt:
    Sendcloud pusht de tracking-updates naar je applicatie zodra deze beschikbaar zijn in Sendcloud.

Sendcloud webhooks

Webhook Integration Object: deze webhook komt in actie wanneer een nieuwe API-integratie wordt toegevoegd aan Sendcloud. Hij wordt geactiveerd wanneer een API integratie wordt aangesloten, verwijderd of bijgewerkt. Klik hier om te zien wat er in de payload van deze webhook staat.

Webhook Parcel Status Changed Object: deze webhook komt in beeld in wanneer de status van een zending verandert; ongeacht wat de statusverandering is. Klik hier om te zien wat er in de payload van deze webhook staat.

Webhook Return Created Object: Deze webhook wordt geactiveerd zodra een retour wordt aangemaakt via de API of het Retourportaal. Klik hier om de details van de payload te bekijken.

Hoe stel je webhooks in Sendcloud in?

Om Sendcloud actief zending updates te laten communiceren (zoals tracking updates), moet je een API endpoint aanmaken. Telkens als er een update plaatsvindt, zal Sendcloud een verzoek doen via dat endpoint. Zie voor meer informatie de Webhooks sectie in onze API documentatie. 

  1. Kopieer de webhook url van je applicatie naar je klembord
  2. Ga naar je Sendcloud panel en open je Integratie instellingen door naar Instellingen > Integraties > Configureren te gaan
  3. Selecteer het vakje bij Webhook feedback ingeschakeld
  4. Zoek het veld Webhook url (zie afbeelding hieronder) en plak daar je webhook url in
  5. Test je webhook door op de Test API webhook knop te klikken
  6. Klik op Opslaan

Klaar! Je webhook is nu ingesteld en de payload zou binnen moeten komen bij je applicatie. Je kunt dit gebruiken om triggers in te stellen die tot bepaalde acties leiden. Een voorbeeld zou zijn om je tracking e-mails te koppelen aan de inkomende tracking updates. Zo kun je je klanten direct updates geven.

Voor retourzendingen ontvang je alleen webhook updates als de uitgaande zending is aangemaakt via de API.

FAQ

Als ik een webhook instel, op welke pakketten is deze dan van toepassing?

Webhooks worden per integratie geconfigureerd. Dit betekent dat de webhook alleen van toepassing is op pakketten die zijn aangemaakt via de integratie waarvoor de webhook is ingesteld. Pakketten die via andere integraties of methoden zijn aangemaakt, activeren deze webhook niet.

Waarom geeft mijn webhook-URL een 404 of is deze onbereikbaar?

Probleem: De webhook-URL is onjuist (bijv. typfout, verkeerde domeinnaam of ontbrekende HTTPS) of het endpoint is niet openbaar bereikbaar.

Voorbeelden:

404 Not Found
DNS resolution failed

Oplossing: Controleer de URL en domeinnaam zorgvuldig. Zorg ervoor dat het endpoint publiek toegankelijk is en HTTPS gebruikt met een geldig SSL/TLS-certificaat.

Waarom zie ik SSL/TLS-certificaatfouten bij mijn webhook?

Probleem: Het endpoint gebruikt een verlopen, zelfondertekend of verkeerd geconfigureerd certificaat.

Voorbeelden:

SSL Handshake failed 
Unable to verify certificate

Oplossing: Installeer een geldig SSL-certificaat van een vertrouwde certificaatautoriteit (CA), vernieuw verlopen certificaten en controleer of tussenliggende certificaten correct zijn geïnstalleerd.

Waarom verlopen webhookverzoeken of reageren ze niet?

Probleem: De server die de webhook ontvangt is te traag of reageert helemaal niet.

Voorbeelden:

 Request timed out
 Connection reset

Oplossing: Zorg ervoor dat de server binnen de time-outlimiet reageert, optimaliseer de code voor snellere verwerking of verplaats zware taken naar achtergrondprocessen. Controleer ook eventuele firewalls of rate limiting.

Waarom geeft mijn webhook HTTP-fouten zoals 405 of 500 terug?

Probleem: Het endpoint verwacht een specifiek HTTP-verzoekstype of geeft geen correcte reactie terug.

Voorbeelden:

405 Method Not Allowed
500 Internal Server Error

Oplossing: Controleer of het endpoint POST-verzoeken accepteert, stuur bij succesvolle ontvangst een statuscode uit de 2xx-reeks terug, en log of verwerk fouten op de juiste manier.

Waarom mislukt de authenticatie of handtekeningverificatie van mijn webhook?

Probleem: De webhookprovider ondertekent verzoeken, maar het endpoint verifieert deze niet correct of gebruikt onjuiste sleutels.

Voorbeelden:

401 Unauthorized 
403 Forbidden

Oplossing: Implementeer HMAC- of handtekeningverificatie met de juiste geheime sleutel en zorg ervoor dat headers en payload exact worden verwerkt zoals ze zijn verzonden.

Waarom is de payload van mijn webhook ongeldig of onjuist opgemaakt?

Probleem: De webhook verzendt JSON of een ander gegevensformaat, maar de ontvangende server kan deze niet correct verwerken.

Voorbeelden:

400 Bad Request
Unexpected token in logs

Oplossing: Controleer of de Content-Type wordt ondersteund (meestal application/json), valideer en log de payload, en update je endpointcode om nieuwe velden of formaten te ondersteunen.

Waarom worden sommige webhookverzoeken beperkt of genegeerd?

Probleem: Het endpoint ontvangt te veel verzoeken en begint daardoor verzoeken te laten vallen.

Voorbeelden:

429 Too Many Requests 
Requests delayed or silently failing

Oplossing: Voeg wachtrijen of throttling toe om pieken op te vangen, implementeer retries met exponentiële backoff, en houd serverbronnen in de gaten of schaal op waar nodig.

Klik hier om naar onze Sendcloud API referentie te gaan en de payload van de webhook te zien.