A webhook channel sends each alert as a signed JSON POST to an HTTPS endpoint you run. This guide covers setup, what each request contains, how to verify it, and what happens when your endpoint fails.
/dashboard/settings/notifications).Not in any policy, and it receives no alerts until you add it to a policy.Delivered (200) or Failed: http_404.The owner copies the signing secret from the channel's Signing secret box with Reveal. It starts with whsec_.
The Delivery box also shows the last delivery, when it happened, and the number of consecutive failures. Failures don't turn a channel off. Stector keeps trying it for later alerts, and the count returns to zero on the next delivery. The dashboard shows the URL only in shortened form, because webhook URLs often contain a credential. To change the URL, enter a new one under Edit. The secret stays the same.
Stector applies these rules when you save and again before every send, because a hostname's DNS can change after it's saved.
https://, and can't be longer than 2,048 characters.localhost and names ending in .localhost, .internal, .flycast or .local.Each delivery is a POST with these headers:
Content-Type: application/json
User-Agent: Stector-Webhooks/1
Stector-Signature: t=1793000000,v1=<64 hex characters>Your endpoint has 10 seconds to answer, covering the whole request. Any 2xx status counts as delivered. Redirects are not followed. Stector reads only the first 4 KB of your response and doesn't use its content.
Every event has the same outer fields:
| Field | Type | Meaning |
|---|---|---|
version | number | The payload format, currently 1. A breaking change gets a new version number. |
id | string | The event id: evt_ and 32 hex characters. See Retries and duplicates. |
createdAt | string | ISO 8601 time this attempt was built. It changes on a retry. |
type | string | monitor.down, monitor.up, monitor.ssl_expiry_warning, monitor.domain_expiry_warning or test. |
data | object | The fields for that type, below. |
Every type except test has data.monitor:
| Field | Type | Meaning |
|---|---|---|
monitor.id | string | The monitor's UUID. |
monitor.name | string | The monitor's name. |
monitor.url | string | What the monitor watches. An HTTP monitor sends its URL and a domain expiry monitor sends its domain. An SSL monitor sends the monitor's name again, not its host. |
downSince is when the monitor went down. statusCode and errorMessage can each be null.
{
"version": 1,
"id": "evt_0123456789abcdef0123456789abcdef",
"createdAt": "2026-11-02T09:14:07.512Z",
"type": "monitor.down",
"data": {
"monitor": {
"id": "3f1c2a54-8e1b-4c6d-9a7f-2b5e8d0c1f34",
"name": "Public API",
"url": "https://api.example.com/health"
},
"downSince": "2026-11-02T09:14:02.000Z",
"statusCode": 503,
"errorMessage": "expected 200, got 503"
}
}upSince is when the monitor recovered. statusCode can be null.
{
"version": 1,
"id": "evt_1123456789abcdef0123456789abcdef",
"createdAt": "2026-11-02T09:21:33.140Z",
"type": "monitor.up",
"data": {
"monitor": {
"id": "3f1c2a54-8e1b-4c6d-9a7f-2b5e8d0c1f34",
"name": "Public API",
"url": "https://api.example.com/health"
},
"upSince": "2026-11-02T09:21:30.000Z",
"statusCode": 200
}
}daysUntilExpiry is whole days, never negative. certNotAfter and certIssuer can each be null. See SSL monitoring for when warnings are sent.
{
"version": 1,
"id": "evt_2123456789abcdef0123456789abcdef",
"createdAt": "2026-11-02T00:03:11.804Z",
"type": "monitor.ssl_expiry_warning",
"data": {
"monitor": {
"id": "7a2d9c10-4b3e-4f8a-8c21-6d1e0f9b3a57",
"name": "API certificate",
"url": "API certificate"
},
"daysUntilExpiry": 14,
"certNotAfter": "2026-11-16T12:00:00.000Z",
"certIssuer": "Let's Encrypt"
}
}domainExpiresAt is always present. expired is true once the registration has lapsed. See Domain expiry monitoring for when warnings are sent.
{
"version": 1,
"id": "evt_3123456789abcdef0123456789abcdef",
"createdAt": "2026-11-02T04:00:52.377Z",
"type": "monitor.domain_expiry_warning",
"data": {
"monitor": {
"id": "c4e81b76-2f5a-4d09-b3c8-91a7e6d2f048",
"name": "example.com registration",
"url": "example.com"
},
"daysUntilExpiry": 30,
"domainExpiresAt": "2026-12-02T18:30:00.000Z",
"expired": false
}
}Sent by Send test. It has no monitor, so check type and never treat it as an outage.
{
"version": 1,
"id": "evt_4123456789abcdef0123456789abcdef",
"createdAt": "2026-11-02T10:02:45.009Z",
"type": "test",
"data": {
"message": "This is a test event from Stector. Your webhook endpoint is reachable."
}
}The Stector-Signature header has the form t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of <t>.<body>, using the channel's whole whsec_ secret as the key, and <body> is the exact bytes you received. Verify before you parse the JSON, because re-serialising it can change the bytes.
We recommend rejecting any timestamp more than 5 minutes from your clock. The timestamp is inside the signature, so nobody can update it without the secret, and an old captured request stops working.
This receiver uses only Node's standard library. Save it as receiver.mjs and run it with STECTOR_WEBHOOK_SECRET=whsec_... node receiver.mjs:
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
const secret = process.env.STECTOR_WEBHOOK_SECRET;
if (!secret) throw new Error('Set STECTOR_WEBHOOK_SECRET');
const TOLERANCE_SECONDS = 5 * 60;
// Keep these somewhere that survives a restart in a real receiver.
const seenEventIds = new Set();
function isValidSignature(header, rawBody) {
const fields = new Map(
(header ?? '').split(',').map((field) => {
const separator = field.indexOf('=');
return [field.slice(0, separator), field.slice(separator + 1)];
}),
);
const t = fields.get('t');
const v1 = fields.get('v1');
if (!t || !/^\d+$/.test(t) || !v1) return false;
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
const received = Buffer.from(v1, 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
}
createServer((req, res) => {
const chunks = [];
req.on('data', (chunk) => chunks.push(chunk));
req.on('end', () => {
const rawBody = Buffer.concat(chunks);
if (!isValidSignature(req.headers['stector-signature'], rawBody)) {
res.writeHead(401).end('invalid signature');
return;
}
const event = JSON.parse(rawBody);
if (seenEventIds.has(event.id)) {
// Answer 2xx so Stector records it as delivered.
res.writeHead(200).end('duplicate');
return;
}
seenEventIds.add(event.id);
console.log(event.type, event.data);
res.writeHead(200).end('ok');
});
}).listen(Number(process.env.PORT ?? 3000));A 401 isn't retried, so an alert your receiver rejects is not sent to it again.
The owner clicks Rotate in the Signing secret box. The old secret stops working immediately, with no overlap, and signatures use the new one from then on. Until you update your receiver, it will reject every alert. Rotate at a quiet moment, then use Send test to confirm.
An alert gets up to 3 attempts: the first, one about 5 seconds later, and one about 10 seconds after that. Each attempt has its own 10-second limit.
| What your endpoint does | Shown as | Result |
|---|---|---|
Answers 2xx | OK (200) | Delivered. No further attempts. |
| Times out after 10 seconds | timeout | Retried |
| DNS or network failure | dns_error, network_error | Retried |
Answers 5xx, 408 or 429 | http_503, for example | Retried |
Answers any other 4xx | http_404, for example | Not retried |
| Answers with a redirect | redirect | Not retried |
| Resolves to a blocked address | blocked_address | Not retried |
After the last attempt, or a failure that isn't retried, a monitor.down or monitor.up event is not sent again. Expiry warnings can get another try, because they repeat: each successful check inside an SSL monitor's warning window queues another attempt that UTC day, and a domain monitor's next daily lookup sends a new warning.
Send test makes one attempt and isn't retried. Each team can send 10 tests an hour.
Each channel accepts up to 5 alerts a minute. Alerts over that limit aren't delivered and aren't retried.
Duplicates can happen. If your endpoint did its work but answered too slowly or with a 5xx, Stector sends the event again. Use id to drop repeats:
id stays the same across retries of the same alert. createdAt and the signature's t change, so don't use them to spot repeats.id, so track ids per endpoint if two channels share a receiver.test event has a new id.Answer quickly and do slow work after responding, so that work doesn't use up the 10 seconds.