Playbooks

Alert webhooks: payload and signature verification

The generic webhook contract for monitoring alerts: the JSON body, the four X-Actuant headers, and how to verify the HMAC-SHA256 signature on your receiver.

Last updated 2026-11-14

Besides email, monitoring alerts can go to Slack, Discord or a generic webhook you run. Add one under Settings > Alert destinations on an app you monitor (Launch, Scale and Max plans, up to 3 per app). This page is the contract for the generic webhook. Slack and Discord deliveries are not signed: their URL is the credential.

Delivery

  • Actuant sends an HTTPS POST with a JSON body. Your URL must be https and resolve to a public address.
  • Redirects are never followed: answer with a 2xx directly. A 3xx counts as a failure.
  • Any 2xx is success. A 429 or 5xx, a timeout or a network error is retried up to 5 times with exponential backoff. Other responses are not retried.
  • After 5 consecutive failed events the destination is disabled and you get one email. Re-enable it in settings.
  • Respond within 10 seconds. The response body is ignored.

Payload

json
{
  "id": "6f1c0a52-0b6e-4a52-9d3e-0a6f4f3f1b9a",
  "type": "regression",
  "createdAt": "2026-11-14T10:00:00.000Z",
  "app": { "host": "example.com" },
  "data": {
    "summary": "Search indexing now failing",
    "score": null,
    "scoreDelta": null,
    "items": [
      { "key": "search-indexing", "label": "Search indexing", "before": "pass", "after": "unknown" }
    ]
  },
  "links": { "app": "https://www.actuant.dev/dashboard/apps/site/example.com", "report": null }
}

score, scoreDelta and links.report can be null, and an item's before and after can be unknown. Treat null as "not known", not as 0.

typeSent when
regressionA re-audit found checks that got worse.
recoveredChecks from an earlier alert are passing again.
testYou pressed Send test.

Headers

HeaderValue
X-Actuant-EventThe type.
X-Actuant-DeliveryThe delivery id, same as id. Stable across retries, so use it to ignore duplicates.
X-Actuant-TimestampUnix seconds at send time. Re-stamped on each retry.
X-Actuant-Signaturev1= followed by the hex HMAC-SHA256 of timestamp + "." + rawBody, keyed with your signing secret.

The signing secret is shown once, when you add the webhook. Actuant stores it encrypted and cannot show it again. If you lose it, remove the destination and add it again.

Verify a delivery

  1. 1

    Use the raw body

    Compute the signature over the exact bytes received, before any JSON parsing or re-serialising.

  2. 2

    Check the timestamp

    Reject the request when X-Actuant-Timestamp is more than 5 minutes from your clock.

  3. 3

    Compare in constant time

    Recompute v1= + HMAC-SHA256 and compare it with X-Actuant-Signature using a constant-time comparison.

  4. 4

    Ignore repeats

    Skip a delivery id you have already handled.

js
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, headers, rawBody) {
  const timestamp = headers["x-actuant-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "v1=" + createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");
  const a = Buffer.from(headers["x-actuant-signature"] ?? "");
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}