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:

HeaderValue
webhook-idThe event's id. It stays the same on every retry.
webhook-timestampWhen this attempt was sent, in Unix seconds. Each retry is stamped again.
webhook-signaturev1,<signature>, one entry per active secret, separated by spaces.
x-actimi-customThe 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.

webhook.ts
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 2xx within 15 seconds and do the work afterwards. Any other status, a timeout or a connection error is a failure.
  • Redirects are not followed; a 3xx is a failure.
  • 410 Gone is not retried: Signals turns the endpoint off. See When deliveries fail.
  • A Retry-After header (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-id as 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 whose data.version is lower than one you handled.

Last updated on

On this page