Webhooks

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

Це міст між сповіщеннями dAio та вашою інформаційною системою.

Порада: почніть з одного webhook, підписаного на один тип події, перевірте весь ланцюжок від початку до кінця, а потім розширюйтеся. Так ви уникнете перевантаження ваших систем сповіщеннями ще до того, як налагодите їх обробку.

Налаштувати webhook

1. Перейдіть до Налаштування > Webhooks.
2. Натисніть Новий webhook.
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	Виявлено високий рівень ризику для вашої діяльності

Порада: підписуйте кожен webhook лише на ті події, які справді використовує система-одержувач. 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. Найменше переформатування змінює хеш і призводить до невдалої перевірки.

Тестування та налагодження

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

Історія доставок

Кожне відправлення журналюється. Розгорніть webhook, щоб для кожної спроби побачити:

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

Лічильник збоїв з'являється на webhook, коли доставки зазнали невдачі.

Повторні спроби та надійність

dAio автоматично повторює доставку в разі збою зі зростаючими інтервалами. Тому ваш endpoint має бути ідемпотентним: одна й та сама доставка може надійти кілька разів, і ваша обробка має давати однаковий результат без побічних ефектів.

Увага: ваш endpoint має відповідати менш ніж за 10 секунд із кодом HTTP 2xx. Понад цей час або в разі коду помилки доставка вважається невдалою і буде повторена. Після повторюваних збоїв webhook автоматично вимикається.

Найкращі практики

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

Порада: поєднуйте ваші webhooks зі сповіщеннями та налаштуванням вашої команди, щоб автоматично спрямовувати потрібну інформацію до потрібної системи. Доступність webhooks залежить від вашої підписки.