Вебхуки. Real-time events, delivered reliably.

Прочитайте необработанное тело запроса в виде байтов (до любого парсинга 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 URL, а затем зарегистрируйте этот URL как конечную точку вебхука в вашей тестовой рабочей области. Кроме того, используйте кнопку тестового запуска вебхука в панели управления, чтобы отправить образец полезной нагрузки для любого типа события на зарегистрированную конечную точку без запуска реального события. Elido CLI (elido webhook test --event click.created --endpoint https://...) также подходит для автоматизированного локального тестирования.

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