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.
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.
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.
| Header | Value | Meaning |
|---|---|---|
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:
| Field | Content |
|---|---|
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,resolvedAtorvalidToare ISO 8601 in UTC.timezoneis the time zone of the account, in whichtextshows the times. causegives the cause of an outage as a code, for exampleTIMEOUT,CONN_REFUSED,DNS_NXDOMAIN,TLS_ERRORorHTTP_5XX. The list may grow.confidence:single_region– confirmed from one location,multi_region– from a second one too.daysLeftis negative ornullwhen the certificate or the domain has already expired.severityiscritical,high,medium,loworinfo;title,what,impactandactionare in the language of the account.- Only sometimes present:
selector,sectionMissing,pageGoneandhttpStatusinkeyword_missing,expiredindomain_expiring. - These fields can also be
null, which is part of their type:helpUrlandlegalDisclaimerinfinding_alert,daysLeftandexpiresAtindomain_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-idonly once. A message can come again even if your system has already processed it, for example when the answer came too late.webhook-timestamp,timestampand 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.