Verify webhooks
Check the signature of every Signals webhook with Standard Webhooks, and handle retries, duplicates and ordering.
Learn how to verify a Signals webhook and what Signals expects from your endpoint. Deliveries follow Standard Webhooks; create the subscriber and pick its events in Signals webhooks.
What Signals sends
Each delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
webhook-id | The event's id. It stays the same on every retry. |
webhook-timestamp | When this attempt was sent, in Unix seconds. Each retry is stamped again. |
webhook-signature | v1,<signature>, one entry per active secret, separated by spaces. |
x-actimi-custom | The subscriber's custom value, when you set one. |
The body is { "type", "timestamp", "sequence", "data" }. Payloads are in Event payloads.
Each signature is the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}. The key is the secret's bytes: drop the whsec_ prefix and base64-decode the rest.
Verify each delivery
Use the subscriber's signingSecret (whsec_…). Verify against the raw body, not re-serialized JSON, and compare in constant time. The Standard Webhooks libraries do both, and reject a webhook-timestamp more than 5 minutes from your clock; Signals sets no tolerance of its own.
import express from 'express';
import { Webhook } from 'standardwebhooks';
const webhook = new Webhook(process.env.SIGNALS_SIGNING_SECRET!);
const app = express();
app.post('/signals/webhook', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = webhook.verify(req.body, req.headers as Record<string, string>);
} catch {
return res.sendStatus(400);
}
res.sendStatus(204);
handle(event);
});Rotate the secret
rotate-secret returns the new secret once. The old one keeps signing for 24 hours, so webhook-signature carries both and a receiver with either secret verifies. Rotate again only after your receiver uses the new secret.
Answer the delivery
- Answer
2xxwithin 15 seconds and do the work afterwards. Any other status, a timeout or a connection error is a failure. - Redirects are not followed; a
3xxis a failure. 410 Goneis not retried: Signals turns the endpoint off. See When deliveries fail.- A
Retry-Afterheader (at most 24 hours) sets a minimum wait before the next attempt.
Retries
Signals makes up to 10 attempts per event. After a failure it waits about 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours, each with up to 20% added. After the tenth failure the event is marked failed; redeliver it once the receiver is fixed.
By default an alert.* event older than 15 minutes is dropped instead of sent, so a late retry never reads as a fresh alarm. A redelivery you ask for is sent whatever its age.
Duplicates and order
- A delivery can arrive more than once. Treat
webhook-idas the idempotency key and skip one you have handled. - Signals sends a subscriber's events in parallel, so they can arrive out of order. Order by
sequence, and for an alert ignore a delivery whosedata.versionis lower than one you handled.
Related
Last updated on
Mutual TLS
Require a client certificate on every call to the Signals API, issue and manage the certificates, and present one from curl, Node.js, Python or Java.
Webhooks
Receive Signals alerts, episodes, readings and patient changes as signed webhooks: subscribers, events, reach, signatures and redelivery.