This product follows widely-adopted open standards so any client — monitoring tools, event platforms, or your own code — can integrate without bespoke work. These conventions are adopted independently; where this document references an external standard, that standard (not this document) is the source of truth.

Versioning

HTTP endpoints are versioned in the path: /v1/.... Breaking changes ship under a new major version.
Event payloads are versioned by the CloudEvents dataschema attribute (a URL to a JSON Schema) and a data.schema_version date string (e.g. 2026-06-26). Adding fields is not breaking; consumers MUST ignore unknown fields.
Deprecation: a deprecated endpoint or schema returns Deprecation: true and Sunset: <HTTP-date> headers (RFC 8594) for at least 6 months before removal. Deprecations are announced in the changelog.

Authentication

API requests authenticate with a bearer token: Authorization: Bearer <token>. Tokens are issued in the dashboard, are scoped, and can be rotated or revoked.
Treat tokens as secrets. Never embed them in client-side code.

Webhook signatures (Standard Webhooks)

Every webhook this product sends, and every webhook it accepts, is signed using the Standard Webhooks scheme.

Each endpoint or subscription has a signing secret (whsec_...).
Each request carries three headers: webhook-id (unique message id, equal to the event id), webhook-timestamp (Unix seconds), and webhook-signature (a space-separated list of v1,<base64 HMAC-SHA256>).
Verify by computing base64(HMAC_SHA256(secret, "{webhook-id}.{webhook-timestamp}.{body}")) and constant-time comparing it against each signature in webhook-signature.
Reject the request if webhook-timestamp is more than 5 minutes from now (replay protection).
Secrets can be rotated; during rotation more than one signature may be present.

Event envelope (CloudEvents)

Events are encoded as CloudEvents 1.0 in structured JSON (Content-Type: application/cloudevents+json).

Attribute	Meaning
`specversion`	Always `1.0`.
`id`	Globally-unique event id. Also the idempotency key (sent as the `webhook-id` header).
`source`	URI identifying the producer, e.g. `https://api.example.app/tenants/{id}`.
`type`	Reverse-DNS event type, e.g. `app.beaam.incident.opened`.
`subject`	The affected resource, e.g. `incident/{id}`.
`time`	RFC 3339 UTC timestamp.
`datacontenttype`	`application/json`.
`dataschema`	URL of the versioned JSON Schema for `data`.
`data`	The event payload (documented per event type).

Idempotency & ordering

Delivery is at-least-once. Consumers MUST deduplicate on the event id (equivalently the webhook-id header).
Events are not strictly ordered. Use time and the resource-state fields in each payload to reconcile. Every event carries enough state to be processed on its own.

Retries & delivery

A delivery succeeds on any 2xx. Respond within 10 seconds; do slow work asynchronously.
Failures (non-2xx, timeout, connection error) are retried with exponential backoff and jitter over roughly 24 hours: immediately, then ~15s, 1m, 5m, 30m, 2h, 6h, then hourly.
Return 410 Gone to permanently stop delivery to an endpoint. 429 with Retry-After is honored.

Errors

Errors use standard HTTP status codes and a JSON body:

{ "error": { "type": "invalid_request", "code": "missing_field", "message": "field 'x' is required", "request_id": "req_..." } }

type is a stable machine-readable category; request_id is for support.

Rate limits

Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until reset). Exceeding the limit returns 429 with a Retry-After header.

This page is generated from docs/api/conventions.md in the Beaam repository, so it stays in step with the implementation. Something unclear or wrong?Tell us — and see theAPI reference for the full list of operations.

Back to docs