Ga naar hoofdinhoud

Webhooks instellen

Laat ShopLinkr je eigen systeem direct een bericht sturen zodra er iets verandert, zoals een nieuwe bestelling.

Met webhooks stuurt ShopLinkr een bericht naar je eigen systeem zodra er iets verandert, bijvoorbeeld als er een nieuwe bestelling binnenkomt of een zending wordt aangemaakt. Je systeem hoeft dan niet steeds zelf bij de API na te vragen of er iets nieuws is. Webhooks zijn bedoeld voor ontwikkelaars en technische partners die een eigen koppeling bouwen.

Endpoint toevoegen

  1. Ga naar Instellingen > Webhooks.

  2. Klik op Endpoint toevoegen.

  3. Geef het endpoint een herkenbare naam, bijvoorbeeld "ERP-koppeling".

  4. Vul de URL in waar ShopLinkr de berichten naartoe stuurt. Dit moet een openbaar https-adres zijn.

  5. Kies bij Events welke gebeurtenissen je wilt ontvangen. De events zijn gegroepeerd, bijvoorbeeld per bestellingen, zendingen, picklijsten, retouren en producten.

  6. Klik onderaan op Endpoint toevoegen.

  7. Kopieer de secret die je daarna te zien krijgt en bewaar hem veilig. Je kunt hem later opnieuw tonen.

Welke events er zijn en wat elk bericht bevat, lees je in de API-documentatie bij Webhook types.

Secret en handtekening

Elk bericht is ondertekend met de secret van het endpoint. Zo controleer je dat een bericht echt van ShopLinkr komt en onderweg niet is aangepast. Hoe je de handtekening controleert, lees je in de API-documentatie over webhooks.

  • Toon secret - Bekijk de secret opnieuw op de pagina van het endpoint.

  • Nieuwe secret - Maak een nieuwe secret aan. De oude werkt direct niet meer, dus pas je ontvanger meteen aan.

Testevent versturen

Klik op de pagina van het endpoint op Testevent versturen. ShopLinkr stuurt dan direct een webhook.test naar je URL, met één poging. Je ziet meteen of het lukte, met de statuscode en hoe lang het duurde. Het testevent staat daarna ook bij de leveringen.

Wat je ontvanger moet doen

  • De verbinding moet binnen 1 seconde staan.

  • Antwoord binnen 5 seconden met een statuscode in de 200-reeks. Wat je in de body terugstuurt, maakt niet uit.

  • Doe het echte werk pas daarna, bijvoorbeeld via een wachtrij. Een time-out telt als mislukt.

  • Een redirect volgen we niet, die telt ook als mislukt.

  • Berichten komen niet altijd op volgorde en heel soms dubbel aan. Gebruik de header webhook-id om dubbele berichten te herkennen.

Leveringen

Onderaan de pagina van het endpoint staan de leveringen: elk bericht dat naar het endpoint is gestuurd, met het event, het aantal pogingen, het antwoord van je systeem, de duur en het tijdstip van de laatste poging. Leveringen blijven 30 dagen zichtbaar.

StatusBeschrijving
In behandelingDe levering staat klaar om verstuurd te worden.
WachtHet endpoint is gepauzeerd. De levering gaat alsnog zodra het endpoint weer werkt.
GeslaagdJe systeem heeft het bericht ontvangen.
MisluktHet bericht kwam na 11 pogingen niet aan, of je systeem gaf 410 Gone terug. Met Opnieuw versturen stuur je de levering nog een keer.
GeannuleerdDe levering is niet verstuurd, bijvoorbeeld omdat het endpoint is gedeactiveerd of de bestelling intussen is verwijderd.

Als je systeem niet bereikbaar is

Mislukt een levering, dan pauzeert ShopLinkr het endpoint. Nieuwe berichten gaan niet verloren, maar krijgen de status Wacht. ShopLinkr probeert telkens één wachtende levering opnieuw: na 30 seconden, 5 minuten, 30 minuten en 1, 2, 5, 10, 15, 20 en 24 uur. Lukt dat, dan gaan alle wachtende berichten alsnog, op volgorde.

  • Na 1 uur pauze krijgt de hoofdgebruiker van je account een e-mail.

  • Werkt het endpoint na 24 uur nog steeds niet, dan deactiveren we het. De wachtende berichten worden dan geannuleerd en de hoofdgebruiker krijgt opnieuw een e-mail.

  • Geeft je systeem 410 Gone terug, dan deactiveren we het endpoint direct.

Heb je het probleem opgelost? Verstuur dan een testevent, of verstuur een mislukte levering opnieuw. Lukt dat, dan hervat het endpoint meteen en hoef je niet op de volgende poging te wachten.

Endpoint weer activeren

Een gedeactiveerd endpoint zet je weer aan met Activeren, op de pagina van het endpoint of in het overzicht. Controleer eerst met een testevent of je ontvanger werkt. Berichten uit de periode dat het endpoint gedeactiveerd was, sturen we niet alsnog. Die haal je zo nodig op via de API.

Wil je een endpoint zelf tijdelijk uitzetten? Klik dan op Endpoint bewerken en zet Actief uit.

Goed om te weten

  • Je kunt maximaal 10 endpoints toevoegen, en elke URL één keer.

  • Alleen openbare https-adressen op poort 443 zijn toegestaan. IP-adressen, localhost en adressen in een intern netwerk weigeren we.

  • Per endpoint sturen we maximaal 5 berichten per seconde.

  • Webhooks beheer je alleen in het dashboard. Standaard heeft alleen de rol Beheerder er toegang toe.

Gerelateerd

Overzicht van de API

API-token aanmaken

Laatst bijgewerkt op

Job Jenniskens

Geschreven door

Job Jenniskens, Oprichter

Begon ShopLinkr vanuit zijn eigen webshop. Bouwt nog steeds elke dag aan het platform en kent elk hoekje van de code.

LinkedIn

Nog vragen?

We helpen je graag verder. Stuur een bericht of plan een gesprek in.