About Webhooks

The Partner API uses webhooks to notify your application about changes that occur for a paired HVAC system, as described in the Event Notification feature. You can leverage these event notifications to execute actions in your application.

What are webhooks?

Webhooks are used as a mechanism to deliver data from an API proactively without further interaction. In this case, the Partner API sends relevant data to registered partner backends asynchronously. Such an event-driven approach ensures sending the right notification to the right application at the time it occurs.

Which event notification types are pushed?

See the event types for a list of all event notifications that can be pushed.

How are the events processed?

As soon as an event occurs in the HVAC system, for example an error, the gateway sends this information to the Bosch Backend. The Backend then analyzes and categorizes the incoming event according to a set of rules. If the event is deemed relevant, it is sent to the Partner API, which then notifies the subscribed clients.

Note that time can pass between a gateway-specific endpoint being called via the Partner API and something happening on the appliance, depending on the specific function and the current state of the appliance. In this case, any related events will be sent by the appliance with an according delay.

The effects of downtimes

During downtimes on the processing chain shown above, e.g. due to maintenance, it can happen that events are lost.

• Gateway: In case the gateway connection is lost, it will not cache events that occur during that time, thus not sending them once the connection is re-established.
• Bosch Backend: Event loss may occur if critical backend components are down. The restart of non-critical components may cause duplicate events to be pushed.
• Client: Events will be lost if the webhook endpoint isn’t available or can’t process the notifications. There is no retry mechanism in place at the moment.

The effects of losing events and potential mitigation options that exist depend on the event type:

Event Type	Impact of Event Loss	How the system will self-heal once the downtime is resolved
Connectivity Status	The last status received via an event may not be the most up to date information.	An event is sent with the latest status as soon as this status changes from its previously reported value (checked every 15 minutes).
Appliance Status	The last status received via an event may not be the most up to date information.	An event is sent with the latest status as soon as the gateway reports its current status.
Contract Status	The last status received via an event may not be the most up to date information.	An event is sent with the latest status as soon as a contract change is triggered.
Data Point - Energy consumption / Electrical power	A gap in the timeline.	Sending events for each new data point value resumes.
Data Point - Operation status	The last status received via an event may not be the most up to date information.	An event is sent with the latest status as soon as this status changes from its previously reported value.
Daily Aggregate	A gap in the timeline.	The event for the next day will be sent.

The effects of slow event processing

The timestamp of each event is not set by the appliance or the gateway but by the Bosch Backend. As a result, the event will always have occurred earlier than indicated by the timestamp.

Accordingly, a slow processing of events has an impact: if any part of the processing chain shown above is slow, e.g. due to a high load, then the timestamp will be affected as more time will pass between the event has occurred and the timestamp being set.

What are the gateway preconditions for receiving events?

There are two preconditions for receiving events for a gateway:

1. The gateway must be paired with your company.
2. The following access authorization must have been granted:
   • Connectivity / Appliance Status events: The Receive notifications of potential faults on system (Error notifications only) permission is sufficient.
   • Data Point and Daily Aggregate events: The Analyse and change all system properties (Monitor and control) permission is required.

Steps to receive events

Webhooks are not enabled by default. Follow the steps below to start receiving event notifications for HVAC systems whose gateways are already paired with your company via HomeCom Pro:

1. Create a webhook endpoint on your backend system.

2. Deploy your webhook endpoint, so it’s a publicly accessible HTTPS URL.

3. Make sure your publicly accessible endpoint is protected with an API key.

4. Share your webhook information in a secure way with us.

   {
       "url": "http://partner.backend/",
       "apiKeyName": "x-api-key",
       "apiKeyLocation": "HEADER",
       "apiKey": "XXX"
   }

5. Inform us about which event types you're interested in receiving.

6. Handle requests from Partner API by parsing each event object and returning 2xx response status codes. The structure of the event payload and examples can be found in the API Reference.

API versioning on receiving events

note

This feature is not yet active.

See API versioning for more information.

In case a breaking change is introduced that impacts an event, the events delivered via the registered webhook will nonetheless continue to be based on the now deprecated API version to ensure that the partner can still process all incoming events. The partner will then need to adapt to the new version of the event within the 6 months that the old API version is still supported. Once the Partner notifies the API developers that they are ready to switch to the new version, or when the API version is no longer supported, the event version will be upgraded to the latest.

The specific version of the API with which an event was processed is included in the HTTP header x-api-version on every event.