Send alerts to a webhook

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.

Before you start

  • Webhooks are on the Pro and Business plans. On Free you can't add a webhook or send a test. If a team moves to Free, its webhook and Slack channels are skipped when an alert is sent, and email still sends.
  • Admins and owners add, edit and delete webhooks and use Send test. Only the owner can see or rotate the signing secret.
  • Your endpoint receives Stector's own JSON format, described below. Discord and Microsoft Teams need their own format and will reject it, and there is no PagerDuty integration. Those three are on the roadmap. For Slack, use the Slack channel.

Add a webhook

  1. Go to Settings → Notifications (/dashboard/settings/notifications).
  2. In the Webhooks section, click Add webhook.
  3. Enter a Name and a URL, then click Add webhook. Stector checks the address before saving it.
  4. Check that the channel is in a policy. If your team has exactly one policy, the webhook is added to it automatically. Otherwise its row shows Not in any policy, and it receives no alerts until you add it to a policy.
  5. In the channel's Delivery box, click Send test. The result appears next to the button, for example 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.

URL rules

Stector applies these rules when you save and again before every send, because a hostname's DNS can change after it's saved.

  • The URL must start with https://, and can't be longer than 2,048 characters.
  • It must use a hostname, not an IP address, and can't contain a username or password.
  • Every address the hostname resolves to must be a public one. Private and internal addresses are refused, including localhost and names ending in .localhost, .internal, .flycast or .local.

What a request looks like

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.

Payload reference

Every event has the same outer fields:

FieldTypeMeaning
versionnumberThe payload format, currently 1. A breaking change gets a new version number.
idstringThe event id: evt_ and 32 hex characters. See Retries and duplicates.
createdAtstringISO 8601 time this attempt was built. It changes on a retry.
typestringmonitor.down, monitor.up, monitor.ssl_expiry_warning, monitor.domain_expiry_warning or test.
dataobjectThe fields for that type, below.

Every type except test has data.monitor:

FieldTypeMeaning
monitor.idstringThe monitor's UUID.
monitor.namestringThe monitor's name.
monitor.urlstringWhat 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.

monitor.down

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"
  }
}

monitor.up

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
  }
}

monitor.ssl_expiry_warning

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"
  }
}

monitor.domain_expiry_warning

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
  }
}

test

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."
  }
}

Verify the signature

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.

Rotate the secret

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.

Retries and duplicates

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 doesShown asResult
Answers 2xxOK (200)Delivered. No further attempts.
Times out after 10 secondstimeoutRetried
DNS or network failuredns_error, network_errorRetried
Answers 5xx, 408 or 429http_503, for exampleRetried
Answers any other 4xxhttp_404, for exampleNot retried
Answers with a redirectredirectNot retried
Resolves to a blocked addressblocked_addressNot 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.
  • A monitor that goes down twice produces two different ids.
  • An SSL or domain expiry warning has one id per monitor per UTC day.
  • Two webhook channels receiving the same alert receive the same id, so track ids per endpoint if two channels share a receiver.
  • Every test event has a new id.

Answer quickly and do slow work after responding, so that work doesn't use up the 10 seconds.