Вебхуки

Через вебхук SitePrio надсилає сповіщення прямо у вашу систему, наприклад у систему заявок чи автоматизацію. Тут описано, що приходить, як перевірити підпис і на що можна покластися.

ЗапитPOST, JSONлише HTTPS, порт 443
Відповідь2xx за 15 свміст не важливий
Спробидо 5з тим самим webhook-id
ПідписHMAC-SHA256за Standard Webhooks

Налаштування

Вебхуки є в тарифах 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.