Rhombus Webhooks

Rhombus webhooks deliver real-time HTTP POST notifications to your server when events occur — door opens, camera alerts, sensor threshold breaches, button presses, and more. Instead of polling the API, your application receives events as they happen.

How webhooks work

1. Add a Webhook

   Add a webhook URL in the console (Settings → Integrations & Developer Resources → Webhooks, with Trigger Type Activity or Diagnostic), or add a webhook action to a rule.

2. Events Occur

   When a subscribed event happens in your Rhombus environment (e.g., a door is forced open), the system generates an event payload.

3. Receive Notifications

   Rhombus sends an HTTP POST request to your registered URL with the event details as a JSON payload.

4. Process & Respond

   Your server returns 200 OK within a few seconds and processes the event afterward. Rhombus doesn't retry a failed delivery; see Delivery.

Event types

Rhombus supports webhook notifications for a wide range of events across your security infrastructure:

Sample webhook payload

When an event triggers a webhook, Rhombus sends a POST request to your URL with a JSON payload. The body depends on the webhook type.

Rule webhook action

{
  "uuid": "event-uuid-here",
  "orgUuid": "org-uuid-here",
  "ruleUuid": "rule-uuid-here",
  "triggeredTimestampMs": 1712678400000,
  "deviceEvents": [
    {
      "eventUuid": "device-event-uuid-here",
      "deviceUuid": "camera-uuid-here",
      "deviceType": "CAMERA",
      "locationUuid": "location-uuid-here",
      "timestampMs": 1712678400000,
      "activities": ["MOTION_HUMAN"]
    }
  ],
  "ruleTriggers": [
    {
      "type": "DEVICE_ACTIVITY_EVENT"
    }
  ]
}

Organization webhook (Activity and Diagnostic)

{
  "version": "2",
  "activityTrigger": "MOTION_HUMAN",
  "summary": "One-line summary of the event",
  "deviceUuid": "camera-uuid-here",
  "location": "location-uuid-here",
  "deviceType": "CAMERA",
  "timestampMs": 1712678400000,
  "alertUuid": "alert-uuid-here",
  "durationSec": 10,
  "thumbnailLocation": "storage-region-here",
  "clipLocationMap": {
    "camera-uuid-here": "storage-region-here"
  }
}

Delivery

The two kinds of webhook are delivered differently:

Rhombus makes one delivery attempt. A delivery that fails (your server is down, slow to connect, or answers with another status) isn't sent again, and a failed rule webhook is recorded as an EXTERNAL_WEBHOOK_FAILURE diagnostic event in your organization. Build your receiver for that:

• Acknowledge first, work later. Return 200 as soon as the signature checks out, and process the event in a queue or background job.
• Reconcile after an outage. Webhooks are a fast path, not a record. After your endpoint has been unavailable, read what you missed from the API, for example policy alerts with getPolicyAlerts (see Pagination).
• De-duplicate and order by the payload. Use the IDs in the body (alertUuid, the event uuid) to ignore repeats, and timestampMs rather than arrival order to sequence events.
• Use HTTPS with a certificate from a public certificate authority.

Verifying webhook signatures

Rhombus signs webhook deliveries so you can confirm that a request came from Rhombus and that the body wasn't changed in transit. Every signed delivery carries x-rhombus-signature-sha256: the HMAC-SHA256 of the raw request body, keyed with that webhook's secret, in lowercase hexadecimal. Verify that header.

The x-rhombus-signature-sha1 header on organization webhooks is an HMAC-SHA1 of the same body with the same secret. You don't need it when you verify x-rhombus-signature-sha256.

For both types:

• Signed content: the exact bytes of the HTTP request body (UTF-8 JSON). Verify the signature before you parse or re-serialize the body.
• Key: the webhook secret string, used as-is (its UTF-8 bytes). Secrets are 22-character base64url strings. Don't decode them.
• Encoding: lowercase hexadecimal.
• Scope: only the body is signed. There's no signed timestamp, so de-duplicate deliveries using IDs in the payload, such as alertUuid or the event uuid.
• One secret per URL: each webhook URL has its own secret. If you register several URLs, store a secret for each.

Find your secret

Organization webhooks. Rhombus creates a secret when you add a webhook URL, and every organization webhook delivery is signed.

• In the console, open Settings → Integrations & Developer Resources → Webhooks and copy the value in the Webhook Secret column.
• With the API, POST /api/integrations/webhooks/updateWebhookIntegrationV2 returns webhookSecret when you add a webhookUrl.
• POST /api/integrations/webhooks/getWebhookIntegration returns each URL's webhookSecret under orgIntegrationV2.activityWebhooksV2 and orgIntegrationV2.diagnosticWebhooksV2.

Rule webhook actions. When you create or update a rule with webhook actions, the response includes webhookSecrets, a map from each webhook URL to its secret. Store it securely.

• Updating a rule keeps the existing secret for URLs that already have one, and creates a secret for new URLs.
• Rhombus always generates these secrets. A secret sent in the request is ignored.
• A webhook action without a secret is delivered without a signature header. Update the rule to assign one.

Verify a request

1. Read the raw request body as bytes, before any JSON parsing.
2. Read the x-rhombus-signature-sha256 header.
3. Compute the HMAC-SHA256 of the raw body with your secret, hex-encode it in lowercase, and compare it with the header in constant time.
4. If the header is missing or doesn't match, respond 401 and discard the request. Otherwise process the event and return 200 OK quickly. Rule webhook actions treat only 200 and 202 as delivered.

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["RHOMBUS_WEBHOOK_SECRET"]


def rhombus_signature_is_valid(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature.strip().lower())  # constant time


@app.post("/rhombus-webhook")
def rhombus_webhook():
    raw_body = request.get_data()  # raw bytes, exactly as sent
    signature = request.headers.get("x-rhombus-signature-sha256", "")  # empty when unsigned
    if not rhombus_signature_is_valid(raw_body, signature, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # ... handle the event ...
    return "", 200

const crypto = require("crypto");
const express = require("express");

const app = express();
const WEBHOOK_SECRET = process.env.RHOMBUS_WEBHOOK_SECRET;

function rhombusSignatureIsValid(rawBody, signature, secret) {
  if (!signature) return false; // unsigned request
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(rawBody).digest("hex"), "utf8");
  const received = Buffer.from(signature.trim().toLowerCase(), "utf8");
  return expected.length === received.length && crypto.timingSafeEqual(expected, received); // constant time
}

// express.raw keeps the body as a Buffer, so the bytes match what Rhombus signed.
app.post("/rhombus-webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!rhombusSignatureIsValid(req.body, req.get("x-rhombus-signature-sha256"), WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // ... handle the event ...
  res.sendStatus(200);
});

app.listen(8080);

Managing webhooks via the API

Organization webhooks are managed with the Webhook Integrations operations:

• getWebhookIntegration reads the configured URLs.
• updateWebhookIntegrationV2 sets the URLs for each trigger type (Activity or Diagnostic).
• deleteWebhookIntegrationV2 removes them.

Each URL receives every notification of its trigger type; there's no filter to set. Rule webhook actions belong to their rule and are managed with the Rules operations in the API Reference.

Implementation guide

Webhook receivers builds a complete receiver: signature checks on the raw body, queuing, reaching systems on a private network without opening it to the internet, and local testing.

No-code alternatives

If you prefer a visual workflow builder over writing custom webhook handlers, Rhombus integrates with:

• Zapier — instant triggers for rule events, button presses, door events, and sensor alerts
• Make.com — webhook triggers with advanced data routing
• n8n — self-hosted webhook processing with AI agent capabilities