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
POSTwith a JSON body. Your URL must behttpsand 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
{
"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.
| type | Sent when |
|---|---|
regression | A re-audit found checks that got worse. |
recovered | Checks from an earlier alert are passing again. |
test | You pressed Send test. |
Headers
| Header | Value |
|---|---|
X-Actuant-Event | The type. |
X-Actuant-Delivery | The delivery id, same as id. Stable across retries, so use it to ignore duplicates. |
X-Actuant-Timestamp | Unix seconds at send time. Re-stamped on each retry. |
X-Actuant-Signature | v1= 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
Use the raw body
Compute the signature over the exact bytes received, before any JSON parsing or re-serialising.
- 2
Check the timestamp
Reject the request when
X-Actuant-Timestampis more than 5 minutes from your clock. - 3
Compare in constant time
Recompute
v1=+ HMAC-SHA256 and compare it withX-Actuant-Signatureusing a constant-time comparison. - 4
Ignore repeats
Skip a delivery id you have already handled.
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);
}Keep reading
Improve your score
A tactical guide to raising your Actuant launch-readiness score quickly — which checks to fix first by weight, how to chase partials for the rest of their weight, and how to verify with re-runs.
API overview
What Actuant exposes over HTTP: an MCP server for programmatic use, a set of public endpoints that need no auth, and dashboard-only routes that will reject an API key.