So far others ask the Kladde: a client calls the API as soon as it wants to know something. But if a partner wants to learn immediately that an
appointment was booked, it would have to ask every few seconds, and almost every time the answer would be “nothing new”. A webhook turns
that around: the partner registers an address, and the Kladde calls it as soon as something happens. In this lesson the Kladde reports
“appointment booked” by webhook. The focus isn't the sending, which is a simple POST, but the questions around it: how does the receiver
know the message really comes from the Kladde? What if it arrives twice? And what if someone enters as the address something that isn't on the
internet at all?
The subscription
A webhook starts with a subscription: a partner tells the Kladde which events it wants sent to which address. For that the Kladde stores:
- the target address, say
https://partner.example/hooks/kladde, - the event types, at first only
example.kladde.booking.created, - a secret that the Kladde generates when the subscription is created (32 random bytes from
RandomNumberGenerator), shows to the partner once and afterward uses only for signing. It never appears in a log and never in an answer of the API. A partner who has lost it gets a new one, and the old one no longer counts.
Subscriptions are created through an endpoint that only the role Management may use (lesson 2.6.3). The management decides who learns when
something is booked; that is data about customers.