Вебхуки
Через вебхук SitePrio надсилає сповіщення прямо у вашу систему, наприклад у систему заявок чи автоматизацію. Тут описано, що приходить, як перевірити підпис і на що можна покластися.
Налаштування
Вебхуки є в тарифах Business і Agency. У SitePrio у розділі «Сповіщення» → «Webhook» вкажіть HTTPS-адресу вашої системи: порт 443, без IP-адреси й без облікових даних в адресі. Ключ підпису (whsec_…) ми показуємо лише один раз: збережіть його надійно.
Які сповіщення приходять, налаштовується там же в «Коли ми вас сповіщаємо». Кнопка «Надіслати тест» перевіряє з’єднання.
Що приходить
На кожне повідомлення SitePrio надсилає на вашу адресу запит POST: у тілі — об’єкт JSON в UTF-8, і ці заголовки.
| Заголовок | Значення | Зміст |
|---|---|---|
content-type | application/json | Тіло — JSON в UTF-8. |
webhook-id | <UUID> | Ідентифікатор повідомлення. Однаковий у всіх спробах одного повідомлення: так ви впізнаєте повтори. |
webhook-timestamp | <Unix> | Час цієї спроби в цілих секундах (час Unix, UTC). |
webhook-signature | v1,<base64> | Підпис повідомлення. Зараз приходить один підпис v1; за стандартом їх може бути кілька через пробіл: перевіряйте кожен. |
Перевірка підпису
Підпис — це HMAC-SHA256 рядка <webhook-id>.<webhook-timestamp>.<тіло> вашим ключем (частина Base64 після whsec_). Бібліотеки Standard Webhooks (для JavaScript, Python, Go, Java, PHP, Ruby та інших) приймають ключ whsec_… як є.
Standard Webhooks: інструкція й бібліотеки
Вручну, тут на Node.js: перевіряйте сире тіло так, як воно прийшло, ще до розбору JSON. Вікно 5 хвилин не дає комусь пізніше надіслати перехоплений запит ще раз.
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);
});
} Для перевірки: з цими значеннями й тілом прикладу 1 у компактному вигляді (JSON.stringify без пробілів і переносів рядків, так воно й надсилається) підпис має збігтися. Для цих тестових значень вимкніть вікно 5 хвилин: вони старші, і інакше verify() їх відхилить.
secret: whsec_AwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMD webhook-id: 019a3f5c-8e40-7b2d-9c41-6f0e2d7a1b35 webhook-timestamp: 1790856300 webhook-signature: v1,MapunbrFrWmC9LJUvh7evkl3aKWb/DavYD5+gwzzFHA=
Будова повідомлення
Кожне повідомлення — це об’єкт JSON із такими полями в такому порядку:
| Поле | Вміст |
|---|---|
type | Вид повідомлення, наприклад incident_down (таблиця нижче). |
category | alert — негайне сповіщення, digest — підсумок години, transactional — тестове повідомлення. |
timestamp | Час цієї спроби (ISO 8601, UTC, з мілісекундами), той самий, що в webhook-timestamp. Час самої події — у data. |
text | Готовий текст, як у Telegram і Slack: тема, порожній рядок, повідомлення. До 3500 знаків, мовою акаунта (de, en або uk). |
data | Дані повідомлення, залежно від виду (нижче). Одноразових посилань у ньому не буває. |
Види повідомлень
Через вебхук приходять лише ці повідомлення. Щотижневий підсумок і місячний звіт — лише електронною поштою, як і все про ваш акаунт, наприклад рахунки.
| Вид | Коли | Головні поля |
|---|---|---|
incident_down | Сайт недоступний. | siteUrl, startedAt, cause, confidence, timezone |
incident_reminder | Сайт усе ще недоступний (нагадування, якщо налаштовано). | siteUrl, startedAt, cause, at |
incident_recovered | Сайт знову доступний (якщо ми повідомляли про збій). | siteUrl, startedAt, resolvedAt, cause |
site_unstable | Три збої за 2 години: одне повідомлення замість багатьох. | siteUrl, count |
site_slow | Сайт помітно повільний (якщо ввімкнено), не частіше разу на добу. | pageUrl, seconds, thresholdSeconds |
keyword_missing | Відстежуваний вміст зник або з’явився небажаний. | pageUrl, keyword, mode, what |
ssl_expiring | SSL-сертифікат скоро спливає або вже сплив. | host, daysLeft, validTo |
ssl_invalid | Сертифікат не підходить до адреси або не довірений. | host, problem |
domain_expiring | Реєстрація домену скоро спливає або вже сплила. | domain, daysLeft, expiresAt |
dns_ns_changed | Змінилися сервери імен домену. | domain, before, after |
finding_alert | Нова проблема, про яку ми повідомляємо одразу. | severity, title, what, impact, action |
grade_up | Загальна оцінка сайту зросла на один щабель (добрі новини, якщо ввімкнено). | siteUrl, gradeFrom, gradeTo, scoreFrom, scoreTo, items, changesUrl |
alert_summary | Наприкінці години, якщо сповіщень було більше ніж 10: усі притримані разом. | items, timezone |
channel_test | Ви надсилаєте тестове повідомлення. | settingsUrl, chat, accountName |
Сповіщення (alert) містять також siteName (назва сайту в SitePrio) і — крім grade_up — dashboardUrl (сайт у SitePrio) та helpUrl (замовити допомогу).
Корисно знати
- Час, як-от
startedAt,resolvedAtчиvalidTo, — ISO 8601 в UTC.timezone— часовий пояс акаунта, у якомуtextпоказує час. causeназиває причину збою кодом, наприкладTIMEOUT,CONN_REFUSED,DNS_NXDOMAIN,TLS_ERRORабоHTTP_5XX. Список може зростати.confidence:single_region— підтверджено з однієї локації,multi_region— і з другої.daysLeftвід’ємне абоnull, якщо сертифікат чи домен уже сплив.severity—critical,high,medium,lowабоinfo;title,what,impactіaction— мовою акаунта.- Лише інколи:
selector,sectionMissing,pageGoneіhttpStatusуkeyword_missing,expiredуdomain_expiring. - Ці поля можуть бути й
null, це частина їхнього типу:helpUrlіlegalDisclaimerуfinding_alert,daysLeftіexpiresAtуdomain_expiring.
Приклади
Приклади взято з акаунта з німецькою мовою. Тут — з відступами; надсилається тіло компактно, без пробілів і переносів рядків.
Приклад 1 — сайт недоступний (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"
}
} Приклад 2 — підсумок години (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"
}
} Приклад 3 — тестове повідомлення (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"
}
} Доставка й повтори
- Повідомлення доставлено, якщо ваша система відповідає статусом 2xx протягом 15 секунд — на весь запит разом зі з’єднанням і TLS. Вміст відповіді ми не читаємо.
- Після 408, 429, 5xx, тайм-ауту чи мережевої помилки ми повторюємо: загалом до 5 спроб, паузи після невдалої спроби — 30 с, 2 хв, 8 хв і 32 хв. Після цього повідомлення більше не надсилається.
- Без повтору: після переадресації (3xx: ми за нею не йдемо), після інших кодів 4xx і коли адреса під час надсилання веде на внутрішню IP-адресу.
- Обробляйте кожен
webhook-idлише один раз. Повідомлення може прийти ще раз, навіть якщо ваша система його вже обробила, наприклад коли відповідь запізнилася.webhook-timestamp,timestampі підпис у кожній спробі нові. - Порядок не гарантується: повтор може прийти після наступного повідомлення. Упорядковуйте за часом події в
data. - Більше ніж 10 сповіщень акаунта за годину: решта приходить разом наприкінці години як
alert_summary. - Вимкнений або видалений вебхук більше нічого не отримує, навіть повторів; так само, якщо тариф більше не містить вебхуків.
На що можна покластися
У повідомленні й у data можуть з’являтися нові поля, нові види (type) і нові значення в переліках, як-от cause. Наявні поля ми не перейменовуємо, не видаляємо й не змінюємо їхній тип.
Тому ігноруйте незнайомі поля й приймайте незнайомий вид теж зі статусом 2xx — наприклад, просто показуйте text.