Webhooks

With a webhook, SitePrio sends alerts straight to your own system, for example a ticket system or an automation. Here is what arrives, how to check the signature and what you can rely on.

RequestPOST, JSONHTTPS only, port 443
Response2xx in 15 scontent is not read
Attemptsup to 5with the same webhook-id
SignatureHMAC-SHA256following Standard Webhooks

Setting up

Webhooks come with the Business and Agency plans. In SitePrio, under “Notifications” → “Webhook”, enter the HTTPS address of your system: port 443, no IP address and no credentials in the address. We show the signing key (whsec_…) only once: keep it safe.

Which alerts come is set there under “When we notify you”. “Send test message” checks the connection.

Go to notifications

What arrives

For every message, SitePrio sends a POST request to your address: a JSON object in UTF-8 as the body, with these headers.

HeaderValueMeaning
content-type application/json The body is JSON in UTF-8.
webhook-id <UUID> ID of the message. The same in every attempt of one message: this is how you recognise retries.
webhook-timestamp <Unix> Time of this attempt in whole seconds (Unix time, UTC).
webhook-signature v1,<base64> Signature of the message. Today there is one v1 signature; the standard allows several separated by spaces: check each one.

Checking the signature

The signature is an HMAC-SHA256 of the string <webhook-id>.<webhook-timestamp>.<body> with your key (the Base64 part after whsec_). The libraries of Standard Webhooks (for JavaScript, Python, Go, Java, PHP, Ruby and more) take the key whsec_… as it is.

Standard Webhooks: guide and libraries

By hand, here in Node.js: check the raw body as it arrives, before you parse the JSON. The 5-minute window stops anyone from sending an intercepted request again later.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
  return String(headers['webhook-signature'] ?? '')
    .split(' ')
    .some((signature) => {
      const [version, value] = signature.split(',');
      const given = Buffer.from(value ?? '', 'base64');
      return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
    });
}

For testing: with these values and the body of example 1 in compact form (JSON.stringify without spaces or line breaks, as it is sent) the signature must match. Switch off the 5-minute window for these test values: they are older, and verify() rejects them otherwise.

secret: whsec_AwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMD
webhook-id: 019a3f5c-8e40-7b2d-9c41-6f0e2d7a1b35
webhook-timestamp: 1790856300
webhook-signature: v1,MapunbrFrWmC9LJUvh7evkl3aKWb/DavYD5+gwzzFHA=

Structure of a message

Every message is a JSON object with these fields, in this order:

FieldContent
type Kind of message, for example incident_down (table below).
category alert – an immediate alert, digest – the summary of the hour, transactional – a test message.
timestamp Time of this attempt (ISO 8601, UTC, with milliseconds), the same as webhook-timestamp. When the event happened is in data.
text The finished text, as in Telegram and Slack: subject, empty line, message. Up to 3500 characters, in the language of the account (de, en or uk).
data The details of the message, depending on its kind (below). It never contains one-time links.

Kinds of messages

Only these messages come by webhook. The weekly digest and the monthly report are email only, as is everything about your account, such as invoices.

Kind When Main fields
incident_down The website is down. siteUrl, startedAt, cause, confidence, timezone
incident_reminder The website is still down (a reminder, if set). siteUrl, startedAt, cause, at
incident_recovered The website is back up (if we reported the outage). siteUrl, startedAt, resolvedAt, cause
site_unstable Three outages within 2 hours: one message instead of many. siteUrl, count
site_slow The website is clearly slow (if switched on), at most once a day. pageUrl, seconds, thresholdSeconds
keyword_missing Monitored content is missing, or unwanted content has appeared. pageUrl, keyword, mode, what
ssl_expiring The SSL certificate expires soon or has expired. host, daysLeft, validTo
ssl_invalid The certificate does not match the address or is not trusted. host, problem
domain_expiring The registration of the domain expires soon or has expired. domain, daysLeft, expiresAt
dns_ns_changed The name servers of the domain have changed. domain, before, after
finding_alert A new problem that we report at once. severity, title, what, impact, action
grade_up The overall grade of the website went up by one step (good news, if switched on). siteUrl, gradeFrom, gradeTo, scoreFrom, scoreTo, items, changesUrl
alert_summary At the end of the hour, if there were more than 10 alerts: all held back ones together. items, timezone
channel_test You send a test message. settingsUrl, chat, accountName

Alerts (alert) also contain siteName (the name of the website in SitePrio) and – except grade_up – dashboardUrl (the website in SitePrio) and helpUrl (request help).

Good to know

  • Times such as startedAt, resolvedAt or validTo are ISO 8601 in UTC. timezone is the time zone of the account, in which text shows the times.
  • cause gives the cause of an outage as a code, for example TIMEOUT, CONN_REFUSED, DNS_NXDOMAIN, TLS_ERROR or HTTP_5XX. The list may grow.
  • confidence: single_region – confirmed from one location, multi_region – from a second one too.
  • daysLeft is negative or null when the certificate or the domain has already expired.
  • severity is critical, high, medium, low or info; title, what, impact and action are in the language of the account.
  • Only sometimes present: selector, sectionMissing, pageGone and httpStatus in keyword_missing, expired in domain_expiring.
  • These fields can also be null, which is part of their type: helpUrl and legalDisclaimer in finding_alert, daysLeft and expiresAt in domain_expiring.

Examples

The examples come from an account in German. Indented here; the body is sent compact, without spaces or line breaks.

Example 1 – the website is down (incident_down):

{
  "type": "incident_down",
  "category": "alert",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "🔴 praxis-sommer.de ist nicht erreichbar\n\nIhre Website https://praxis-sommer.de/ ist seit 01.10.2026, 14:02 Uhr nicht erreichbar.\n\nWAS IST PASSIERT?\nIhr Server antwortet nicht (Zeitüberschreitung nach 15 Sekunden). Wir haben das dreimal innerhalb von 2 Minuten geprüft.\n\nWAS BEDEUTET DAS FÜR SIE?\nBesucher sehen gerade eine Fehlerseite statt Ihres Angebots. Online-Anfragen und -Buchungen sind nicht möglich.\n\nWAS KÖNNEN SIE JETZT TUN?\nPrüfen Sie, ob Ihr Hosting-Anbieter eine Störung meldet, und kontaktieren Sie die Person, die Ihre Website betreut. Oder wir kümmern uns darum.\n\nDetails ansehen: https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b\nHilfe anfordern (Notfall-Hilfe): https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b/help?service=emergency_help\n\nWir melden uns automatisch, sobald Ihre Website wieder erreichbar ist.\n\nTECHNISCHE DETAILS\nGeprüft von: 1 Standort (Deutschland)\nErgebnis: Server antwortete nicht (3 von 3 Prüfungen)\nBeginn: 01.10.2026, 14:02 (Europe/Berlin)\nUrsache (Code): TIMEOUT\nAdresse: https://praxis-sommer.de/\n\n— SitePrio",
  "data": {
    "siteName": "praxis-sommer.de",
    "siteUrl": "https://praxis-sommer.de/",
    "startedAt": "2026-10-01T12:02:00.000Z",
    "cause": "TIMEOUT",
    "timezone": "Europe/Berlin",
    "confidence": "single_region",
    "dashboardUrl": "https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b",
    "helpUrl": "https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b/help?service=emergency_help"
  }
}

Example 2 – summary of the hour (alert_summary):

{
  "type": "alert_summary",
  "category": "digest",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "2 weitere Warnungen in der letzten Stunde\n\nIn der letzten Stunde gab es mehr als 10 Warnungen. Damit Ihr Postfach nicht überläuft, fassen wir die weiteren hier zusammen:\n\n- 01.10.2026, 13:41 Uhr: 🔴 praxis-sommer.de ist nicht erreichbar\n- 01.10.2026, 13:52 Uhr: ✅ praxis-sommer.de ist wieder online\n\nDie Details sehen Sie in Ihrem Dashboard.\n\n— SitePrio",
  "data": {
    "items": [
      {
        "subject": "🔴 praxis-sommer.de ist nicht erreichbar",
        "at": "2026-10-01T11:41:07.000Z"
      },
      {
        "subject": "✅ praxis-sommer.de ist wieder online",
        "at": "2026-10-01T11:52:30.000Z"
      }
    ],
    "timezone": "Europe/Berlin"
  }
}

Example 3 – test message (channel_test):

{
  "type": "channel_test",
  "category": "transactional",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "Testnachricht von SitePrio\n\nDieser Chat erhält ab jetzt Sofort-Warnungen zu den Websites von Praxis Sommer.\n\n— SitePrio",
  "data": {
    "settingsUrl": "https://app.guard.findyour.dance/notifications",
    "chat": true,
    "accountName": "Praxis Sommer"
  }
}

Delivery and retries

  • A message is delivered when your system answers with a 2xx status within 15 seconds, for the whole request including connection and TLS. We do not read the content of the answer.
  • After 408, 429, 5xx, a timeout or a network error we try again: up to 5 times in total, the pauses after a failed attempt are 30 s, 2 min, 8 min and 32 min. After that we give up on the message.
  • There is no new attempt after a redirect (3xx: we do not follow it), after the other 4xx codes and when the address points to an internal IP address at the time of sending.
  • Process each webhook-id only once. A message can come again even if your system has already processed it, for example when the answer came too late. webhook-timestamp, timestamp and the signature are new in each attempt.
  • The order is not guaranteed: a retry can arrive after the next message. Sort by the time of the event in data.
  • More than 10 alerts of one account in an hour: the others come together at the end of the hour as alert_summary.
  • A webhook that is switched off or deleted gets nothing more, not even retries; the same when the plan no longer includes webhooks.

What you can rely on

New fields in the message and in data, new kinds (type) and new values in lists such as cause may be added. We do not rename or remove existing fields and do not change their type.

So ignore unknown fields and accept an unknown kind with 2xx too, for example by simply showing text.