Skip to main content

​
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

MethodHeaderWho It Applies To
API Keyx-auth-apikeyDeveloper and Partner Developer accounts
OAuth Tokenx-auth-access-tokenOAuth-authorized applications
Both methods share the same rate limiting behavior described below.

​
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 DetailValue
Status code429
Retry-After header60 (seconds)
Body"Too many api requests. Enhance your calm."

​
Handling a 429 Response

  1. Read the Retry-After header. It tells you how many seconds to wait before retrying.
  2. Pause requests for the duration specified (60 seconds).
  3. 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. Exponential backoff with jitter is the most resilient approach for any integration: 
delay = min(base_delay * 2^attempt + random_jitter, max_delay)
ParameterRecommended Value
Base delay1 second
Max delay60 seconds
Max retry attempts5-10
JitterRandom 0-1 second
Example implementation (pseudocode): 
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

TypeTriggerUse Case
ActivityDevice events, alert activityMotion detection, door access, face/vehicle alerts
DiagnosticSystem health eventsDevice offline, connectivity issues

​
Configuration

Each webhook is identified by its destination URL and includes:
FieldDescription
webhookSecretShared secret for verifying payload signatures
webhookDisabledToggle to temporarily disable delivery without deleting the webhook
You can register multiple webhooks per type. Each URL can be independently enabled or disabled.

​
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
2. Verify the signature. Use the 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 ResponseWhat Rhombus Does
200-299Marks as delivered; applies backoff window before next delivery
410 GoneMarks your webhook as inactive; stops sending
429Enters backoff; retries after a delay
Any other errorRetries with backoff
5. Keep your endpoint available. If your endpoint is consistently unreachable or returning errors, delivery attempts will continue with increasing backoff periods.

​
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

OptionSeconds
1 Minute60
2 Minutes120
5 Minutes (default)300
10 Minutes600
20 Minutes1200
30 Minutes1800
1 Hour3600
This is set per policy and per activity type. During the backoff window, duplicate alerts for the same entity and activity are suppressed server-side. Alerts with new identity information (a different recognized face or license plate) bypass the backoff and are delivered immediately.

​
Quick Reference

ScenarioWhat To Do
Received 429 from the APIRead Retry-After header, wait that many seconds, then retry
Received 5xx from the APIRetry with exponential backoff (1s, 2s, 4s, … up to 60s)
Received 4xx (not 429) from the APIDo not retry — fix the request
Webhook receiving duplicate eventsDeduplicate using event identifiers; return 200 promptly
Webhook endpoint going offline temporarilyRhombus retries with backoff; events will be redelivered when you return
Webhook endpoint permanently removedReturn 410 Gone so Rhombus stops delivery
Too many alerts for same eventConfigure alert backoff interval in policy settings (default 5 min)