Webhooks: een seintje naar je eigen systeem

Een webhook stuurt een seintje naar je eigen systeem zodra er iets gebeurt in je zaak: een nieuw lid, een betaling, een boeking. Je CRM, je mailprogramma, Zapier of Make hoort het dan meteen, zonder dat het steeds hoeft te vragen of er iets nieuws is.

Wie het kan. Webhooks horen bij het pakket met de publieke API (Gym en hoger), net als de API-sleutels. Alleen de eigenaar van de zaak stelt ze in. Ga je naar een pakket zonder API, dan blijven je webhooks staan, maar ze sturen niets meer.

Instellen. Ga naar Praktijk & systeem → Koppelingen en kies bij Webhooks Nieuwe webhook.

1. Vul het adres in waar de berichten heen moeten. Alleen https, op poort 443 of 8443. Een intern of lokaal adres (localhost, 10.x, 192.168.x) kan geen webhook ontvangen.
2. Kies de gebeurtenissen waar je een seintje van wilt.
3. Kies Aanmaken. Je ziet nu één keer het geheim. Kopieer het meteen naar je systeem; wij laten het niet nog eens zien. Kwijt? Kies bij de webhook Geheim vernieuwen. Het oude geheim werkt dan meteen niet meer.
4. Kies Test versturen. Binnen een minuut zie je in het logboek of je systeem de test ontving.

De gebeurtenissen.

• lid.nieuw: iemand wordt actief lid van je zaak. Met het id, de naam en het e-mailadres van het lid, zodat je systeem de nieuwe klant meteen kan aanmaken.
• lidmaatschap.gewijzigd: een nieuw lidmaatschap, een ander abonnement of een andere status (gepauzeerd, opgezegd, verlopen). Met de naam van het lid.
• betaling.geslaagd en betaling.mislukt: een termijn of bestelling is betaald, of kon niet worden afgeschreven. Met het bedrag in centen en de naam van het lid.
• afspraak.geboekt en afspraak.geannuleerd: een les of afspraak is geboekt of afgezegd. Zonder de naam van het lid en zonder de naam van de dienst: bij een praktijk zegt dat al iets over iemands gezondheid.
• ping: het bericht van Test versturen.

Wat er in een bericht staat. Elk bericht is een POST met JSON: id, type (de gebeurtenis), aangemaakt_op, zaak_id en data. In data staan id's, tijden, bedragen en statussen, en waar hierboven genoemd de naam. Het e-mailadres staat alleen bij lid.nieuw. Nooit een telefoonnummer, adres of iets uit een dossier. Meer nodig? Haal het op met een API-sleutel; zie Je eigen systemen koppelen.

De handtekening controleren. Zo weet je systeem dat een bericht echt van ons komt. Elk bericht heeft deze headers:

• X-xBase360-Event: de gebeurtenis, bijvoorbeeld lid.nieuw.
• X-xBase360-Delivery: het id van de levering. Krijg je hetzelfde id twee keer, dan is het hetzelfde bericht; verwerk het één keer.
• X-xBase360-Timestamp: het tijdstip van deze poging, in seconden sinds 1970.
• X-xBase360-Signature: t=<tijdstip>,v1=<handtekening>.

Je systeem rekent de handtekening na: HMAC-SHA256 met je geheim over het tijdstip, een punt en de ruwe body, dus over <t>.<body>, als hex. Komt die uit op v1, dan klopt het bericht. Gebruik de body precies zoals hij binnenkwam, niet na het inlezen en opnieuw opmaken van de JSON. Weiger een bericht waarvan het tijdstip meer dan vijf minuten afwijkt; zo kan niemand een oud bericht opnieuw afspelen. Een voorbeeld in code staat op de pagina Koppelingen.

Antwoorden en opnieuw proberen. Antwoord binnen tien seconden met een 2xx. Lukt dat niet, dan proberen we het opnieuw na 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur en 24 uur; daarna geven we het op. Een omleiding (3xx) volgen we niet. In het logboek zie je de laatste honderd berichten met hun stand en code; een mislukt bericht stuur je daar met Opnieuw nog eens. Na dertig dagen gaan ze uit het logboek.

Pauzeren. Met het vinkje Aan bij Bewerken zet je een webhook zelf op pauze: er gaat niets naartoe en er komt niets nieuws in de wachtrij. Weer aanzetten verstuurt wat er nog wacht. Mislukt een adres tien keer achter elkaar en al langer dan een dag, dan pauzeren we de webhook zelf. Herstel dan je systeem, kies Test versturen, en zet hem weer aan als de test lukt.