Webhooks instellen

Met een API-sleutel haalt een ander programma jouw gegevens op wanneer het die nodig heeft. Met een webhook draait het om: wij sturen een bericht naar een adres van jou zodra er iets gebeurt.

Dat scheelt wachten. Een bestelling die om kwart over acht binnenkomt, staat om kwart over acht in je boekhouding — en niet bij de volgende ronde, een uur later.

Waar klanten dit voor gebruiken:

• elke verkoop meteen in de boekhouding of in een eigen databank;
• een schermpje aan de ingang dat toont wie er net binnenkwam;
• een bericht in een groepschat zodra een rondleiding uitverkocht is;
• een eigen mail of sms naar de koper, bovenop de onze.

Dit artikel is de handleiding bij het scherm, stap voor stap. Wil je eerst weten wat een webhook is en of je er een nodig hebt, lees dan Webhooks.

Goed om te weten: webhooks horen bij dezelfde formule als de API. Zit je op een kleinere formule, dan staat API-toegang niet in je menu; kom je toch op het scherm terecht, dan zie je uitleg en een knop Naar Abonnement.

Waar je moet zijn

Open in het menu links Instellingen → API-toegang en klik bovenaan op het tabblad Webhooks. Alleen de rol eigenaar ziet dit scherm.

Je ziet drie blokken: Wij bellen jou (uitleg), Nieuwe bestemming (het formulier) en Bestemmingen (wat er al is).

Wat je nodig hebt

Eén ding, en het moet er al zijn voor je begint: een adres op je eigen server dat berichten kan ontvangen. Dat is een stukje programmeerwerk aan jouw kant — je webbouwer of je boekhoudpakket weet wat je bedoelt als je zegt "een endpoint voor webhooks".

Drie eisen:

1. Het moet https zijn. Een gewoon http-adres weigeren we: er gaan gegevens van kopers over die lijn.
2. Het moet van buitenaf bereikbaar zijn. Een adres binnen je eigen kantoornetwerk (iets met 192.168. of 10.) kunnen wij niet bereiken, en we weigeren het ook.
3. Het moet snel antwoorden. Wij wachten tien seconden. Duurt de verwerking langer, laat je server dan meteen "ok" zeggen en daarna pas verder werken.

Een bestemming toevoegen

Stap 1. Vul het adres in. In het eerste veld (https://...) het volledige adres waar wij naartoe mogen sturen, bijvoorbeeld https://boekhouding.mijnbedrijf.be/webhooks/tickets.

Stap 2. Zeg waarvoor het is. Het tweede veld (Waarvoor is dit?) is niet verplicht, wel handig. "Onze boekhouding", "scherm aan de kassa". Heb je er straks drie, dan weet je zo welke waarbij hoort.

Stap 3. Vink aan waarover we je mogen berichten. Onder Waarover willen we je berichten? staat de lijst. Dit is de belangrijkste keuze. Vink alleen aan wat je echt verwerkt: elk bericht dat je niet gebruikt, is werk voor je server en ruis in je logboek. Minstens één vakje moet aan; een bestemming zonder berichten zou nooit iets krijgen.

Bericht	Wanneer het vertrekt
Bestelling aangemaakt	Er is een bestelling ontstaan (een winkelmandje telt niet mee).
Bestelling betaald	Het geld is binnen.
Bestelling geannuleerd	De bestelling is geannuleerd of vervallen.
Bestelling terugbetaald	Er is geheel of gedeeltelijk terugbetaald.
Ticket aangemaakt	Er is een ticket uitgegeven.
Ticket gescand	Er is gescand aan de ingang — ook wanneer het geweigerd werd.
Ticket ingetrokken	Een ticket is ingetrokken of terugbetaald.
Tijdslot uitverkocht	Een tijdslot zit vol.
Tijdslot weer vrij	Er is weer plaats in een vol tijdslot.
Cadeaubon uitgegeven	Er is een bon verkocht.
Cadeaubon verzilverd	Er is van een bon afgeboekt.
Jaarkaart uitgegeven	Er is een jaarkaart aangemaakt.
Kassasessie afgesloten	Een kassalade is geteld en dicht.
Factuur uitgereikt	Er is een factuur of creditnota aan een koper gemaakt.

Stap 4 (optioneel). Testbestemming. Wijst het adres naar een testomgeving, vink dan Testbestemming (krijgt alleen testgebeurtenissen) aan. Meer daarover onder "Een testbestemming" hieronder.

Stap 5. Klik op Bestemming toevoegen.

Je kan tot twintig bestemmingen hebben. Heb je er al twintig, verwijder er dan eerst één.

Het geheim zie je maar één keer

Meteen daarna verschijnt een geheim: een lange reeks die begint met whsec_.

Kopieer het nu en geef het door aan wie de koppeling bouwt. Ververs je de pagina of wissel je van tabblad, dan is het weg.

Met dat geheim ondertekenen wij elk bericht dat we naar jouw adres sturen. Jouw server kan daarmee nagaan dat het bericht écht van ons komt en niet van iemand die je adres ergens opving. Dat is geen luxe: zonder die controle is jouw endpoint een open deur waar iedereen bestellingen doorheen kan gooien.

Ben je het geheim kwijt? Klik op Nieuw geheim. Je krijgt meteen een nieuwe en de oude werkt vanaf dat moment niet meer — vergeet dus niet ze ook aan de andere kant te vervangen.

Voor wie de koppeling bouwt staat op het developersportaal precies hoe je die handtekening narekent, met voorbeelden in PHP, JavaScript en Python. Via de API kan hij ook een ondertekend voorbeeldbericht opvragen om zijn eigen code tegen te testen, zonder eerst een verkoop te moeten doen.

Testen zonder verkoop

Klik naast een bestemming op Proefbericht. Wij sturen dan één bericht van het soort test.ping — geen echte gegevens, alleen een seintje.

Daaronder opent meteen het berichtenlog, zodat je ziet wat je server antwoordde. Staat er Aangekomen, dan werkt het. Staat er een foutcode, dan weet je waar je moet kijken. Een proefbericht vertrekt ook naar een bestemming die uit staat.

Het berichtenlog

Klik naast een bestemming op Berichten. Je ziet de laatste vijftig berichten, en per bericht:

• welk soort het was en wanneer het vertrok;
• wat je server terugstuurde (het getal is de http-status; 200 betekent "ok");
• hoe vaak we het geprobeerd hebben;
• hoe het ervoor staat: Aangekomen, Onderweg (we proberen het nog) of Niet afgeleverd.

Is een bericht niet aangekomen, dan kun je met Opnieuw proberen hetzelfde bericht nog eens aanbieden. Handig nadat je een storing aan jouw kant opgelost hebt.

Berichten blijven dertig dagen staan. Daarna worden ze opgeruimd: het log is er om een probleem mee te vinden, niet als archief.

Wat er gebeurt als je server het even niet doet

Wij geven niet meteen op. Komt een bericht niet aan, dan proberen we het zes keer opnieuw, met steeds langere tussenpozen: na een minuut, vijf minuten, een half uur, twee uur, twaalf uur en een dag. Samen ruim anderhalve dag.

Lukt het dan nog niet, dan:

• krijgt de bestemming het merkteken Komt niet door;
• krijg je één mail. Die gaat naar de Contact-e-mail van je organisatie, of naar het Factuuradres (e-mail) als dat eerste leeg is (allebei onder Instellingen → Organisatie, tabblad Contact);
• blijft de bestemming gewoon aanstaan. Volgende gebeurtenissen worden opnieuw aangeboden, en zodra er weer iets aankomt, verdwijnt het merkteken.

Je krijgt hoogstens één zo'n mail per dag per bestemming. Een server die een weekend plat ligt, levert dus geen honderd mails op.

Een testbestemming

Vink bij het aanmaken Testbestemming aan wanneer het adres naar een testomgeving wijst. Zo'n bestemming krijgt alleen testgebeurtenissen — wat er gebeurt met de proefbestellingen van een testsleutel — en nooit echte verkoop. Ze draagt in de lijst het merkteken Test. Omgekeerd krijgt een gewone bestemming nooit iets van een proefbestelling.

Die scheiding is hard, en met opzet: een testserver die per ongeluk een echte bestelling verwerkt, stuurt een bevestiging naar een echte koper.

Uitzetten of verwijderen

Uitzetten stopt de leveringen maar laat de bestemming staan, met haar geheim en haar berichtenlog; ze krijgt het merkteken Uit. Handig tijdens onderhoud aan jouw kant. Klik opnieuw op Aanzetten en het loopt weer.

Verwijderen haalt de bestemming én haar berichtenlog weg. Dat kan niet ongedaan gemaakt worden; een nieuwe bestemming krijgt een nieuw geheim.

Er is nog een derde geval: antwoordt jouw server ooit met de code 410, dan zetten wij de bestemming zelf uit. Die code betekent letterlijk "dit adres bestaat niet meer", en dan is blijven aankloppen onbeleefd. Hetzelfde gebeurt wanneer het adres intussen naar een intern netwerk wijst. Klik op Aanzetten zodra het weer in orde is.

Drie tips voor wie de koppeling bouwt

1. Antwoord eerst, verwerk daarna. Zeg meteen "ok" en doe het echte werk in de achtergrond. Anders loop je tegen onze tien seconden aan.
2. Verwerk idempotent. Elk bericht draagt een eigen nummer (de Idempotency-Key). Komt hetzelfde nummer twee keer binnen, doe dan niets. Wij proberen bij twijfel opnieuw, en een dubbele boeking is erger dan een dubbele logregel.
3. Reken niet op de volgorde. Twee berichten kunnen elkaar inhalen wanneer het eerste herhaald wordt. Kijk naar de tijd in het bericht en naar de inhoud, niet naar de volgorde van aankomst.

Verder lezen

• Webhooks — wat een webhook is en wanneer je er een nodig hebt, zonder technische termen.
• Een API-sleutel aanmaken — het andere tabblad van dit scherm.
• Het developersportaal — voor wie de koppeling bouwt.