Webhooks

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

Это мост между оповещениями dAio и вашей информационной системой.

Совет : начните с одного вебхука, подписанного на один тип события, проверьте всю цепочку от начала до конца, а затем расширяйте. Так вы избежите того, чтобы захлестнуть свои системы уведомлениями до того, как обработка станет надёжной.

Настройка вебхука

1. Перейдите в Настройки > Вебхуки.
2. Нажмите Новый вебхук.
3. Укажите URL назначения: HTTPS-endpoint вашего сервера (например, https://votre-serveur.com/webhook).
4. Выберите события для прослушивания, нажимая на соответствующие метки.
5. Подтвердите кнопкой Создать.

При создании автоматически генерируется секрет. Он служит для подписи каждого запроса по HMAC-SHA256 (см. ниже): храните его на стороне сервера — он позволяет вам убедиться, что каждый вызов действительно исходит от dAio.

Внимание : URL должен быть в формате HTTPS и доступен публично. Endpoint на обычном HTTP или за закрытым межсетевым экраном не сможет получать доставки.

Доступные события

Событие	Описание
weather.alert	На объекте сработало погодное оповещение
weather.threshold	Превышен пользовательский погодный порог
air_quality.alert	Выпущено оповещение о качестве воздуха
pollen.alert	Выпущено оповещение о пыльце
marine.alert	Выпущено оповещение о морских условиях
frost.alert	Сработало оповещение о заморозках
storm.alert	Сработало оповещение о грозе / буре
business.risk_high	Для вашей деятельности обнаружен высокий уровень риска

Совет : подписывайте каждый вебхук только на те события, которые действительно используются системой-получателем. Endpoint «тикеты» не нуждается в тех же событиях, что и endpoint «дашборд».

Формат payload

Каждая доставка — это запрос POST, тело которого представляет собой объект JSON. Общая структура следующая:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

Поле event определяет тип события, timestamp указывает время отправки (UTC, формат ISO 8601), а data содержит детали, характерные для события.

Аутентификация HMAC-SHA256

Каждый запрос подписывается вашим секретом с помощью HMAC-SHA256. Подпись передаётся в заголовке X-Daio-Signature в формате sha256=<signature>.

Всегда проверяйте эту подпись перед обработкой запроса: именно это гарантирует, что вызов исходит от dAio и payload не был изменён.

Проверка на стороне сервера (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Внимание : вычисляйте подпись по необработанному телу запроса (полученным байтам), до любой десериализации JSON. Малейшее переформатирование меняет хеш и приводит к сбою проверки.

Тестирование и отладка

• Нажмите значок Тест (▶) рядом с вебхуком, чтобы отправить фиктивное событие на ваш endpoint.
• HTTP-ответ 2xx подтверждает, что ваш сервер получил и принял запрос.
• Разверните вебхук, чтобы просмотреть его последние доставки: HTTP-код, тип события и временную метку.
• Цветная точка показывает состояние вебхука: зелёный = активен, красный = отключён после повторных сбоев.

История доставок

Каждая отправка фиксируется в журнале. Разверните вебхук, чтобы увидеть для каждой попытки:

• HTTP-код ответа (зелёный, если < 300, иначе красный)
• Тип события, который был доставлен
• Дату и время попытки

Счётчик сбоев отображается на вебхуке, когда доставки завершились неудачно.

Повторные попытки и надёжность

dAio автоматически повторяет доставку в случае сбоя, с возрастающими интервалами. Поэтому ваш endpoint должен быть идемпотентным: одна и та же доставка может прийти несколько раз, и ваша обработка должна давать тот же результат без побочных эффектов.

Внимание : ваш endpoint должен ответить менее чем за 10 секунд с HTTP-кодом 2xx. По истечении этого времени или при коде ошибки доставка считается неудачной и будет повторена. После повторных сбоев вебхук автоматически отключается.

Лучшие практики

• Всегда проверяйте подпись HMAC перед обработкой payload: никогда не доверяйте неаутентифицированному запросу.
• Отвечайте быстро: немедленно возвращайте 200, а затем обрабатывайте нагрузку в фоновом режиме. Вы избежите тайм-аутов и ненужных повторов.
• Сделайте вашу обработку идемпотентной, чтобы безопасно поглощать множественные доставки.
• Фильтруйте у источника: подписывайте каждый вебхук только на события, полезные для его системы-получателя.
• Следите за счётчиком сбоев и историей доставок, чтобы быстро обнаружить вышедший из строя endpoint до того, как он будет отключён.
• Используйте кнопку Тест после каждого изменения с вашей стороны (развёртывание, смена URL), чтобы проверить цепочку, не дожидаясь реального события.

Совет : сочетайте ваши вебхуки с оповещениями и настройками вашей команды, чтобы автоматически направлять нужную информацию в нужную систему. Доступность вебхуков зависит от вашей подписки.