Webhooks

A booking is a piece of information other devices could put to good use. The heating that should come up a quarter of an hour beforehand. The lights that go on. The display in the foyer that switches over. Webhooks deliver that information: at the start or end of a booking, Zeitwart sends an HTTP request to an address you store.

The most important dial: the offset

Reporting an event exactly at the start is often too late. An offset therefore shifts the moment: -15 on the event start trigger sends the request a quarter of an hour earlier – enough time to warm a room or switch a display. +5 on event end clears up afterwards.

What you set per webhook

• the organisational unit whose bookings it reacts to

• the target URL and the trigger: start, end or content change

• the offset in minutes, negative or positive

• an optional room filter – empty means every room in the unit

• whether the full booking object is sent along

• additional payload fields as free key-value pairs

Several webhooks can therefore run alongside each other and react differently to the same event – one for building services, one for the display, one for a third-party system.

Signed, because otherwise it would be dangerous

Every webhook can carry a signing secret with which Zeitwart signs the request. The recipient uses it to verify that the message really came from here. An endpoint that opens doors on request should not be operated without that check.

Traceable

A delivery log records every attempt. If the ventilation once failed to start, that tells you whether Zeitwart did not report it or the target system did not accept it – a question that otherwise tends to stay open for a long time.

Typical applications

• bring heating and ventilation up before the start, lower them afterwards

• switch the lighting and sound of an event space

• release doors and access points for the booked period

• switch signage and information screens to the next appointment

• report booking events to a third-party system

Benefits at a glance

• report booking events to any system, with no detour through the API

• offset in minutes – lead time for building services, follow-up for clearing away

• configurable per organisational unit and optionally per room

• signing secret to protect security-relevant endpoints

• a delivery log covering every attempt