Webhooks
Was passiert ist, ohne zu fragen.
KRONENWERK ruft Ihre Adresse an, sobald in den Büchern etwas geschieht, das Sie angemeldet haben. Jede Zustellung ist unterschrieben, und jede wird wiederholt, bis sie angenommen wird.
| Ereignis | Wann es gesendet wird |
|---|---|
| invoice.issued | Eine Rechnung wurde ausgestellt: die Nummer ist vergeben, das Dokument ist archiviert und unveränderlich. |
| invoice.paid | Eine Rechnung ist vollständig ausgeglichen — durch eine Zahlung, gleich auf welchem Weg sie erfasst wurde. |
| invoice.cancelled | Eine Rechnung wurde storniert: es gibt einen Stornobeleg, der sie vollständig aufhebt. Gelöscht wird nichts. |
| purchase.recorded | Eine Eingangsrechnung oder eine Ausgabe wurde erfasst, mit Lieferant, Datum und Beträgen. |
| payment.recorded | Eine Zahlung wurde erfasst, mit Richtung, Betrag, Tag und dem Beleg, den sie ausgleicht. |
| bank.transaction.imported | Ein Bankumsatz wurde eingelesen und steht zur Zuordnung bereit. |
| kronenwerk.test | Eine Probezustellung, die Sie selbst auslösen, um Ihre Prüfung zu testen. |
Die Prüfung, vollständig.
Die Reihenfolge trägt: erst der Zeitstempel, dann die Prüfsumme. Eine wiedereingespielte alte Zustellung hat eine tadellose Prüfsumme, und nur ihr Alter verrät sie. Vergleichen Sie in konstanter Zeit und über die rohen Bytes, nicht über neu erzeugtes JSON.
# KRONENWERK-Signature: t=1775462400,v1=9f86d0…
t, v1 = parse(header) # t=<unix seconds>, v1=<hex hmac>
if abs(now() - t) > 300: reject() # replay window, checked first
expected = hmac_sha256(key=endpoint_secret, msg=f"{t}.{raw_body}").hexdigest()
if not constant_time_equals(expected, v1): reject()
accept() # then dedupe on Idempotency-KeyRechnen Sie mit Doppelten.
Jede Zustellung trägt eine Idempotenzkopfzeile mit der Kennung des Ereignisses. Eine Antwort, die uns nicht erreicht, führt zu einem weiteren Versuch mit derselben Kennung — merken Sie sich diese Kennung, und ein zweiter Eingang ändert bei Ihnen nichts.
Wiederholung
Sechs Versuche, dann steht es im Protokoll.
Antwortet Ihr Empfänger nicht mit einem Erfolg, versucht KRONENWERK es erneut: nach dreissig Sekunden, dann mit jedem Mal doppelt so lange, bis zu sechs Versuchen. Danach gilt die Zustellung als fehlgeschlagen und steht mit Zeitpunkt, Status und Antwortauszug im Protokoll, wo Sie sie von Hand erneut senden können. Endlos wiederholt wird nichts.