Developer API
A Secure Heartbeat API Built for Applications
The Tier 1 API uses HMAC-SHA256 authentication, replay-aware request fields, idempotent signal creation, authenticated polling and explicit ACK.
Endpoint contract
| Method | Path | Purpose |
|---|---|---|
| POST | /heartbeat/create | Create a pending signal for a target application. |
| GET | /heartbeat/signals | Read pending signals for the authenticated target. |
| POST | /heartbeat/ack/<signal-id> | Confirm a signal after the receiving business action. |
Diagnostics such as /heartbeat/health and /heartbeat/benchmark are local/operator paths, not customer integration endpoints.
Authentication
Authenticated requests carry X-HBH-Application, X-HBH-Timestamp, X-HBH-Nonce, X-HBH-Request-Id and X-HBH-Signature. Create also carries an Idempotency-Key. The signature covers the uppercase method, logical path, timestamp, nonce, request ID, idempotency key and SHA-256 hash of the raw body.
METHOD\nPATH\nTIMESTAMP\nNONCE\nREQUEST_ID\nIDEMPOTENCY_KEY\nSHA256(raw_body)Create, read and ACK
Create uses a JSON object with target_application_id and payload. A successful create returns a random sig_ identifier and pending status. The target reads pending signals in creation order and receives up to the configured Tier 1 read limit. Reading does not ACK or remove a signal. The target ACKs after its business action.
Retries and errors
When a create response is unknown, reuse the same business idempotency key and create fresh timestamp, nonce, request ID and signature values. Do not reuse an exact request ID or nonce. Honor Retry-After on 429 responses. Errors use application/problem+json with stable machine categories.
Boundaries
Tier 1 is for small JSON signals. The current implementation rejects unsafe floating-point and integer values, enforces a request body limit and applies authenticated application rate limiting. It does not include webhook delivery, credential rotation HTTP endpoints, exactly-once execution or large-payload transport.
For exact headers, validation rules and tested examples, use the maintained API reference in the project documentation.