Documentation Index
Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
Use this file to discover all available pages before exploring further.
Rhombus API Rate Limits & Webhooks — Developer Guide
This guide covers what you need to know to build reliable integrations with the Rhombus API, including how rate limiting works, how to handle throttled responses, and how to configure and consume webhooks.
API Rate Limits
All API requests authenticated via API key or OAuth token are subject to rate limiting. Limits are enforced per credential and per organization.
Authentication Methods
| Method | Header | Who It Applies To |
|---|
| API Key | x-auth-apikey | Developer and Partner Developer accounts |
| OAuth Token | x-auth-access-token | OAuth-authorized applications |
What Happens When You Hit the Limit
When your request is rate limited, the API returns:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: text/plain
Too many api requests. Enhance your calm.
| Response Detail | Value |
|---|
| Status code | 429 |
Retry-After header | 60 (seconds) |
| Body | "Too many api requests. Enhance your calm." |
Handling a 429 Response
- Read the
Retry-After header. It tells you how many seconds to wait before retrying.
- Pause requests for the duration specified (60 seconds).
- Retry your request after the wait period.
Do not immediately retry on a 429 — repeated requests while rate limited will continue to be rejected and will not reset your limit window.
Recommended Client-Side Strategy
Exponential backoff with jitter is the most resilient approach for any integration:
delay = min(base_delay * 2^attempt + random_jitter, max_delay)
| Parameter | Recommended Value |
|---|
| Base delay | 1 second |
| Max delay | 60 seconds |
| Max retry attempts | 5-10 |
| Jitter | Random 0-1 second |
function callApi(request):
for attempt in 0..max_retries:
response = http.send(request)
if response.status == 200:
return response
if response.status == 429:
wait = parseRetryAfterHeader(response) // use Retry-After when available
sleep(wait)
continue
if response.status >= 500:
delay = min(1 * 2^attempt + random(0, 1), 60)
sleep(delay)
continue
// 4xx errors (other than 429) are not retryable
throw ClientError(response)
throw MaxRetriesExceeded()
Key Points
- Rate limits are evaluated per API key / OAuth token per organization.
- The
Retry-After header is always present on 429 responses — always prefer it over hardcoded delays.
- Server errors (5xx) are transient and safe to retry with backoff. Client errors (4xx other than 429) indicate a problem with your request and should not be retried.
- The rate limiting system is fail-open — if the rate limit service itself is unavailable, your request will be allowed through. Do not rely on this behavior; design your integration to respect limits.
Webhooks
Webhooks allow your application to receive real-time event notifications via HTTP POST to a URL you configure. Webhook delivery, retry, and backoff are handled entirely server-side — your responsibility is to register your endpoint and process incoming payloads.
Webhook Types
| Type | Trigger | Use Case |
|---|
| Activity | Device events, alert activity | Motion detection, door access, face/vehicle alerts |
| Diagnostic | System health events | Device offline, connectivity issues |
Configuration
Each webhook is identified by its destination URL and includes:
| Field | Description |
|---|
webhookSecret | Shared secret for verifying payload signatures |
webhookDisabled | Toggle to temporarily disable delivery without deleting the webhook |
Webhook Lifecycle
Register URL + Secret ─> Events occur ─> Rhombus POSTs to your URL
│
┌──────────┴──────────┐
│ │
2xx Success Non-2xx Failure
(delivered) (server retries
with backoff)
Delivery Behavior
The server manages delivery with built-in backoff:
- Successful delivery (2xx): Event is marked as delivered. A configurable backoff window prevents duplicate deliveries for the same event type.
- Rate limited (429): The server enters a backoff period for your webhook URL and retries later.
- Gone (410): Your webhook is marked as inactive. Re-register if your endpoint returns to service.
- Other failures (non-2xx): The server logs the error and retries according to its backoff schedule.
Building a Reliable Webhook Receiver
1. Respond quickly. Return a 200 OK as soon as you receive the payload. Process the event asynchronously.
POST /your-webhook-endpoint
# Good: acknowledge immediately, process later
return 200 OK
queue_for_processing(payload)
# Bad: process synchronously before responding
result = heavy_processing(payload)
return 200 OK
webhookSecret to validate that the payload came from Rhombus and has not been tampered with.
3. Handle duplicates. Webhook delivery is at-least-once. Your receiver should be idempotent — processing the same event twice should produce the same result. Use event identifiers to deduplicate.
4. Return appropriate status codes.
| Your Response | What Rhombus Does |
|---|
200-299 | Marks as delivered; applies backoff window before next delivery |
410 Gone | Marks your webhook as inactive; stops sending |
429 | Enters backoff; retries after a delay |
| Any other error | Retries with backoff |
Alert Backoff (Notification Throttling)
Alert notifications (distinct from webhooks) have a configurable minimum interval between consecutive alerts of the same type for a given entity. This prevents alert fatigue from high-frequency events like motion detection.
Configurable Intervals
| Option | Seconds |
|---|
| 1 Minute | 60 |
| 2 Minutes | 120 |
| 5 Minutes (default) | 300 |
| 10 Minutes | 600 |
| 20 Minutes | 1200 |
| 30 Minutes | 1800 |
| 1 Hour | 3600 |
Quick Reference
| Scenario | What To Do |
|---|
Received 429 from the API | Read Retry-After header, wait that many seconds, then retry |
Received 5xx from the API | Retry with exponential backoff (1s, 2s, 4s, … up to 60s) |
Received 4xx (not 429) from the API | Do not retry — fix the request |
| Webhook receiving duplicate events | Deduplicate using event identifiers; return 200 promptly |
| Webhook endpoint going offline temporarily | Rhombus retries with backoff; events will be redelivered when you return |
| Webhook endpoint permanently removed | Return 410 Gone so Rhombus stops delivery |
| Too many alerts for same event | Configure alert backoff interval in policy settings (default 5 min) |
