Webhooks

Eine Buchung ist eine Information, die andere Geräte gut gebrauchen könnten. Die Heizung, die eine Viertelstunde vorher hochfahren sollte. Das Licht, das angeht. Die Anzeige im Foyer, die umschaltet. Webhooks liefern diese Information dorthin: Beim Beginn oder Ende einer Buchung schickt Zeitwart eine HTTP-Anfrage an eine Adresse, die du hinterlegst.

Der wichtigste Regler: der Offset

Ein Ereignis genau zum Terminbeginn zu melden, kommt oft zu spät. Deshalb verschiebt ein Offset den Zeitpunkt: -15 beim Auslöser Veranstaltungsbeginn schickt die Anfrage eine Viertelstunde vorher – genug Zeit, um einen Raum vorzuwärmen oder eine Anzeige umzuschalten. +5 beim Veranstaltungsende räumt entsprechend nach.

Was du je Webhook einstellst

• die Organisationseinheit, auf deren Buchungen er reagiert

• die Ziel-URL und den Auslöser: Beginn, Ende oder Inhaltsänderung

• den Offset in Minuten, negativ oder positiv

• einen optionalen Raum-Filter – leer bedeutet: alle Räume der Einheit

• ob das vollständige Buchungsobjekt mitgeschickt wird

• zusätzliche Payload-Felder als freie Schlüssel-Wert-Paare

Damit lassen sich mehrere Webhooks nebeneinander betreiben, die auf dasselbe Ereignis unterschiedlich reagieren – einer für die Gebäudetechnik, einer für die Anzeige, einer für ein Drittsystem.

Signiert, weil es sonst gefährlich wäre

Jeder Webhook kann ein Signing-Secret tragen, mit dem Zeitwart die Anfrage signiert. Der Empfänger prüft damit, dass die Meldung wirklich von hier kommt. Ein Endpunkt, der auf Zuruf Türen öffnet oder Technik schaltet, sollte ohne diese Prüfung nicht betrieben werden.

Nachvollziehbar

Ein Zustellprotokoll zeigt jeden Versuch. Wenn die Lüftung einmal nicht angesprungen ist, lässt sich damit unterscheiden, ob Zeitwart nicht gemeldet oder das Zielsystem nicht angenommen hat – eine Frage, die ohne Protokoll erfahrungsgemäß lange offen bleibt.

Typische Anwendungen

• Heizung und Lüftung vor Terminbeginn hochfahren, danach absenken

• Licht und Beschallung eines Veranstaltungsraums schalten

• Türen und Zutrittspunkte für den gebuchten Zeitraum freigeben

• Anzeigen und Infoscreens auf den nächsten Termin umstellen

• Buchungsereignisse an ein Drittsystem melden

Vorteile auf einen Blick

• Buchungsereignisse an beliebige Systeme melden, ohne Umweg über die API

• Offset in Minuten – Vorlauf für Technik, Nachlauf fürs Aufräumen

• je Organisationseinheit und optional je Raum konfigurierbar

• Signing-Secret zur Absicherung sicherheitsrelevanter Endpunkte

• Zustellprotokoll über jeden Versuch