Bisher fragen andere die Kladde: Ein Client ruft die API, sobald er etwas wissen will. Will ein Partner aber sofort erfahren, dass ein Termin
gebucht wurde, müsste er alle paar Sekunden fragen, und fast immer lautete die Antwort „nichts Neues“. Ein Webhook dreht das um: Der
Partner hinterlegt eine Adresse, und die Kladde ruft dort an, sobald etwas geschieht. In dieser Lektion meldet die Kladde „Termin gebucht“ per
Webhook. Dabei steht nicht das Senden im Mittelpunkt, das ist ein einfaches POST, sondern die Fragen drumherum: Woran erkennt der Empfänger,
dass die Nachricht wirklich von der Kladde kommt? Was, wenn sie zweimal ankommt? Und was, wenn jemand als Adresse etwas einträgt, das gar nicht
im Internet liegt?
Das Abonnement
Ein Webhook beginnt mit einem Abonnement: Ein Partner sagt der Kladde, welche Ereignisse er an welche Adresse geschickt haben will. Die Kladde speichert dazu:
- die Zieladresse, etwa
https://partner.example/hooks/kladde, - die Ereignisarten, zunächst nur
example.kladde.booking.created, - ein Geheimnis, das die Kladde beim Anlegen erzeugt (32 Zufallsbytes aus
RandomNumberGenerator), dem Partner einmal zeigt und danach nur noch zum Signieren benutzt. Es steht nie in einem Log und nie in einer Antwort der API. Ein Partner, der es verloren hat, bekommt ein neues, und das alte gilt nicht mehr.
Angelegt werden Abonnements über einen Endpunkt, den nur die Rolle Leitung benutzen darf (Lektion 2.6.3). Die Leitung entscheidet, wer
erfährt, wann gebucht wird; das sind Daten über Kundschaft.