Вебхуки. Події в реальному часі, надійна доставка.

Зчитайте сире тіло запиту як байти (до будь-якого парсингу JSON), обчисліть HMAC-SHA256 для цих байтів, використовуючи спільний секрет вашої кінцевої точки, закодуйте результат у base16 (hex) і порівняйте його зі значенням у заголовку X-Elido-Signature, видаливши префікс 'sha256='. Використовуйте функцію порівняння за сталий час (наприклад, hmac.compare_digest у Python, crypto.timingSafeEqual у Node.js), щоб запобігти атакам за часом. Ніколи не порівнюйте підпис за допомогою стандартного оператора рівності рядків. Приклади коду для Node.js, Python та Go доступні за адресою /docs/guides/webhooks#verification.

Поверніть HTTP 200 (або будь-який код статусу 2xx) протягом 30 секунд. Тіло відповіді ігнорується - ви можете повернути порожнє тіло або { ok: true }. Якщо ваша обробка триває довше 30 секунд, негайно поверніть 200 і обробляйте подію асинхронно (помістіть у внутрішню чергу, поверніть 200, обробляйте поза шляхом запиту). Повернення 4xx розцінюється так само, як 5xx, для цілей повторної спроби - обидва варіанти ініціюють повтор. Повертайте 200, навіть якщо подія не стосується вашої інтеграції (наприклад, подія link.created, яка вам не потрібна), щоб уникнути зайвих повторних спроб.

Кожне корисне навантаження вебхука містить поле event_id (UUID). Використовуйте його як ключ ідемпотентності у своєму приймачі: якщо ви отримуєте один і той самий event_id двічі (через повторну спробу після часткового збою), обробіть його лише один раз. Зберігайте отримані ID подій у таблиці дедуплікації з TTL не менше 72 годин (вікно повторних спроб). Навантаження повторної спроби ідентичне оригінальному - той самий event_id, те саме тіло - тому простої перевірки 'чи бачив я вже цей event_id?' достатньо.

Кінцеві точки автоматично призупиняються після 30 послідовних помилок доставки (код не 2xx або таймаут). Це не дає Elido нескінченно атакувати несправну кінцеву точку. Усуньте основну проблему (зазвичай: URL кінцевої точки змінився, сервер не працює або 30-секундний таймаут перевищується через повільну обробку), а потім відновіть роботу кінцевої точки на панелі керування. Після відновлення Elido не перевідправляє автоматично події, які були пропущені під час паузи - відправте їх вручну з журналу доставки, якщо вам потрібно їх відновити.

Так - увімкніть режим raw-click для кінцевої точки. У режимі raw-click Elido доставляє події click.created індивідуально без вікна пакетування протягом 2 секунд після кліка. Майте на увазі, що активний робочий простір може генерувати тисячі подій за хвилину в режимі raw-click; переконайтеся, що ваш приймач витримає таку пропускну здатність. Для більшості аналітичних сценаріїв використання за замовчуванням достатньо 5-секундної пакетної агрегації (до 100 кліків у корисному навантаженні), що створює значно менше HTTP-запитів.

Розмір індивідуального корисного навантаження події не перевищує 10 КБ. Пакетні навантаження кліків (режим за замовчуванням) можуть містити до 100 подій у пакеті, з загальним обмеженням розміру 100 КБ. Якщо пакет перевищує 100 КБ, він автоматично розбивається на кілька доставок. Великі поля метаданих у кліках (наприклад, довгі URL реферерів) обрізаються до 2 КБ на кожне поле. Якщо ваш приймач має суворе обмеження розміру корисного навантаження, налаштуйте режим raw-click (одна подія на доставку) замість пакетного режиму.

Використовуйте такі інструменти, як ngrok, Cloudflare Tunnel або localtunnel, щоб відкрити свій локальний сервер за допомогою публічної HTTPS-адреси, а потім зареєструйте цю адресу як кінцеву точку вебхука у своєму тестовому робочому просторі. Крім того, скористайтеся кнопкою тестового запуску вебхука на панелі керування, щоб надіслати зразок корисного навантаження для будь-якого типу події на зареєстровану кінцеву точку, не створюючи реальну подію. Elido CLI (elido webhook test --event click.created --endpoint https://...) також підходить для автоматизованого локального тестування.

Події, згенеровані під час технічного обслуговування, ставляться в чергу в нашому потоці подій і доставляються після завершення робіт. Сторінка статусу Elido (status.elido.app) заздалегідь повідомляє про заплановане технічне обслуговування. SLA доставки вебхуків не поширюється на анонсовані вікна технічного обслуговування. Для типового 30–60 хвилинного вікна обслуговування 72-годинне вікно повторних спроб означає, що жодна подія не буде остаточно втрачена - вони будуть доставлені в порядку їх створення, щойно кінцева точка знову стане доступною.