Rhombus API offers webhooks which allow users to setup their own HTTPS server as an endpoint for receiving Rhombus alerts.

Webhooks

We offer a single webhook url per organization. When enabled, we POST a webhook payload for every alert that is generated in our system. These alerts are driven by the policies that devices are assigned to.

The webhook payload is a JSON object with the following fields and typing:

{
  "version": [INTEGER] the version of the webhook,
  "activityTrigger": [STRING] optional comma separated list of activities that triggered the alert (human movement, etc),
  "diagnosticTrigger": [STRING] optional comma separated list of diagnostics that triggered the alert (camera disconnects, etc),
  "summary": [STRING] user friendly description of the alert,
  "deviceUuid": [STRING] the id of the device that triggered the alert,
  "timestampMs": [LONG] the epoch millisecond timestamp of the alert,
  "location": [STRING] the id of the location for the alert,
  "alertUuid": [STRING] the id of the alert,
  "durationSec": [INTEGER] optional duration of the alert clip in seconds if the alert has media,
  "thumbnailLocation": [STRING] optional region of the alert thumbnail if the alert has media,
  "clipLocationMap": [MAP<STRING, STRING>] optional map of device id to region for the alert clip
}

Below is an example webhook payload with default values:

{
  'summary': 'Movement detected at Headquarters', 
  'deviceUuid': 'XXXXXXXXXXXXXXXXXX',
  'clipLocationMap': {'XXXXXXXXXXXXXXXXXX': 'us-west-2'}, 
  'alertUuid': 'XXXXXXXXXXXXXXXXXXX', 
  'activityTrigger': 'MOTION',
  'location': 'XXXXXXXXXXXXXXXX', 
  'durationSec': 8, 
  'version': '2', 
  'timestampMs': 1646942680190, 
  'thumbnailLocation': 'us-west-2'
}

You can update the webhook integration either through the console or by using the API endpoint found below:

https://apidocs.rhombussystems.com/reference/updatewebhookintegrationv2

An example of setting up a development ngrok server for webhook payload consumption can be found hyperlinked here.

This example prints the webhook payload and saves the clip to local storage.

Securing Webhooks

There are two general approaches for ensuring that webhooks received by your server originated from Rhombus. Ideally, both of these approaches should be implemented by all webhook consumers.

Validate the Client certificate presented during the TLS handshake

The following certificate can be used, in combination with a check for the CN (webhook-client.rhombus.com) to validate that the connection has originated from Rhombus

https://cacerts.digicert.com/DigiCertTLSRSASHA2562020CA1-1.crt.pem

Paste the link above in your browser.

Validate the HMAC header included in the request header

Every webhook request contains the header x-rhombus-signature-sha1. This signature should be used to compare against the following operation, to ensure the authenticity of the content of each webhook request.

The webhook secret is unique to each organization, and can be found here: https://console.rhombussystems.com/settings/integrations/webhookSettings

final String webhookSignature = new HmacUtils(HmacAlgorithms.HMAC_SHA_1, webhookSecret)
					.hmacHex(webhookBody);

import hmac
import hashlib

digester = hmac.new(webhookSecret, webhookBody, hashlib.sha1)
signature = digester.digest().encode("hex")