Webhooks

Вебхук — канал для тех, кто хочет связать оповещение со своими инструментами: скриптом, информационной доской состояния, системой дежурств, небольшим сервисом, который заводит заявку. Когда сайт перестаёт работать и когда он снова начинает, UptimeWire отправляет один HTTP-запрос на заданный вами адрес.

Что передаёт вебхук

Предупреждения о сертификате, домене и DNS вебхуком не отправляются. Они приходят по почте и, если подключён, в Telegram.

Как настроить

Адрес задаётся в вашем аккаунте UptimeWire, в настройках уведомлений профиля. Добавить, изменить, проверить или удалить его может только владелец аккаунта.

1. Введите адрес вашего получателя. Он должен начинаться с https://.
2. Нажмите «Save address». При первом сохранении создаётся секрет подписи.
3. Скопируйте секрет подписи в своего получателя. Он начинается с whsec_.
4. Нажмите «Send test message». Результат показывается сразу.

Адрес один для всех сайтов в аккаунте. Выбрать отдельный адрес для одного сайта нельзя.

Какие адреса принимаются

UptimeWire отклоняет адрес, который:

• не использует https:// или содержит имя пользователя или пароль;
• указывает на частную или внутреннюю сеть, на сам компьютер или на числовой обход вроде IP-адреса в десятичной или шестнадцатеричной записи;
• длиннее 2 048 знаков.

Адрес проверяется при сохранении и ещё раз перед отправкой каждого сообщения.

Сообщение

Запрос — это HTTP POST с телом в формате JSON. Этот пример показан для иллюстрации: значения выдуманы.

{
  "id": "4182",
  "event": "incident.opened",
  "site": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Shop",
    "url": "https://shop.example.com"
  },
  "incident": {
    "id": "00000000-0000-0000-0000-000000000001",
    "started_at": "2026-11-01T10:15:00Z",
    "ended_at": null,
    "duration_seconds": null,
    "cause": "HTTP 503"
  }
}

Для incident.closed тело такое же, но поля ended_at и duration_seconds заполнены. Для test поля site и incident равны null. Время указано по UTC.

Поле id определяет доставку, а не инцидент. Часть про инцидент показывает его состояние на момент отправки сообщения, поэтому запоздавшее incident.opened уже может содержать ended_at. Игнорируйте неизвестные вам поля, чтобы ваш получатель продолжал работать, если появится новое поле.

Заголовки

Проверка подписи

Любой, кто узнает ваш адрес, может отправить на него запрос. Подпись позволяет вашему получателю отличить настоящее сообщение UptimeWire от поддельного.

Подпись — это HMAC с SHA-256, записанный в шестнадцатеричном виде. Она вычисляется вашим секретом подписи от текста, составленного из времени t, точки и необработанного тела.

Чтобы проверить сообщение:

1. Прочитайте необработанное тело до того, как разбирать его как JSON. Разбор и повторная запись могут его изменить.
2. Возьмите t и v1 из заголовка X-UptimeWire-Signature.
3. Вычислите HMAC от t, точки и необработанного тела с вашим секретом подписи.
4. Сравните свой результат с v1 сравнением за постоянное время.
5. Отклоните сообщение, если t отличается от показаний ваших часов больше чем на пять минут.

Если вы создадите в аккаунте новый секрет, старый перестанет работать сразу. Периода совместной работы нет.

Доставка и повторные попытки

Доставка считается успешной, если ваш получатель отвечает статусом 2xx в течение пяти секунд. Всё остальное — сбой: другой статус, превышено время ожидания, проблема с сертификатом или отказ в соединении. UptimeWire не следует за перенаправлениями, и ответ 3xx — это сбой.

Неудавшееся сообщение пробуют отправить всего до пяти раз: сразу, затем через 1, 5, 30 и 120 минут. После последней попытки оно помечается как неудавшееся. UptimeWire не присылает вам об этом письмо, но панель показывает, что оповещение не доставлено. Адрес он не отключает.

В редких случаях одно и то же сообщение может прийти дважды, а сообщения могут приходить не по порядку. Сохраняйте id каждого обработанного сообщения и по started_at определяйте, какое состояние новее.

Что видно в вашем аккаунте

В карточке вебхука в вашем аккаунте есть журнал доставки с последними 20 сообщениями. Для каждого показаны сайт, тип сообщения, статус (доставлено, не удалось, будет повторено, ожидает или отменено), число попыток и результат, например «Answered 200».

Ограничения

• Один адрес на аккаунт, общий для всех сайтов. Изменить его может только владелец аккаунта.
• Только сбой и восстановление.
• Входит в тариф Starter и выше. Если аккаунт переходит на тариф без вебхуков, ожидающие сообщения отменяются, а новые не создаются. Адрес и секрет сохраняются, и после повышения тарифа сообщения возобновляются.
• Сообщения отправляются как минимум один раз, а не ровно один раз.
• UptimeWire не читает ответ, который присылает ваш получатель.

Устранение неполадок

• «This address is not allowed.» Адрес ведёт в частную или внутреннюю сеть. Используйте публичный адрес.
• "The address must start with https://." Обычный http:// не принимается.
• «The address did not answer in 5 seconds.» Сначала отвечайте, а медленную работу делайте потом, например поставив сообщение в очередь.
• «Answered 3xx: redirects are not followed.» Укажите конечный адрес.
• Сообщения приходят, но подпись не совпадает. Проверьте, что вы вычисляете её от необработанного тела и используете текущий секрет.
• «Too many test messages.» Кнопка проверки ограничена пятью нажатиями в минуту.

Telegram, Discord, Slack и Microsoft Teams — отдельные каналы. Что передаёт каждый из них, смотрите в обзоре интеграций.