Полезно знать - Ограничения вебхуков и поведение системы

Понимание того, как finlight обрабатывает ошибки, повторы и ограничения вебхуков, помогает создавать более надёжные интеграции и эффективно управлять квотой.

Обработка ошибок и повторы

Логика повторов

Когда доставка вебхука завершается неудачей, finlight автоматически повторяет запрос:

График повторов:

• 1-й повтор: Сразу после первоначального сбоя
• 2-й повтор
• 3-й повтор

Максимум попыток:

• Всего 3 попытки доставки на событие вебхука
• Каждый повтор использует ту же полезную нагрузку и заголовки
• Все попытки повтора фиксируются в истории вызовов

Что вызывает повторы

Повторы происходят при:

• Кодах ошибок HTTP ответы 4xx и 5xx
• Сетевых тайм-аутах (лимит 5 секунд)
• Сбоях соединения (ошибки DNS, отклонённые соединения)
• Ошибках SSL/TLS (проблемы с сертификатом)

Что не вызывает повторы

Повторов нет при:

• Ответах HTTP 2xx (считаются успешными)
• Недопустимой конфигурации вебхука (некорректные URL)
• Отключённых вебхуках

Защита автоотключения

Отслеживание последовательных сбоев

finlight отслеживает последовательные сбои вебхука, чтобы защитить вашу квоту и предотвратить бесконечные неудачные попытки.

Как это работает:

1. Успех сбрасывает счётчик - Любая успешная доставка (HTTP 2xx) сбрасывает счётчик сбоев до 0
2. Сбои увеличивают счётчик - Каждая неудачная доставка увеличивает счётчик последовательных сбоев
3. Автоотключение на 10 - После 10 последовательных сбоев вебхук автоматически отключается

Поведение автоотключения

Когда срабатывает автоотключение:

• 10 последовательных неудачных доставок по всем попыткам повтора
• Статус вебхука меняется с «включён» на «отключён»
• Появляется уведомление в панели, указывающее на автоотключение
• Больше попыток вебхука нет до ручного повторного включения

Важные примечания:

• К автоотключению учитываются только последовательные сбои
• Любая успешная доставка сбрасывает счётчик до 0
• Требуется ручное повторное включение - вебхуки не включаются сами
• Все типы сбоев учитываются (тайм-ауты, ответы 4xx, 5xx)

Примеры сценариев

Сценарий 1: Сброс счётчика

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

Сценарий 2: Автоотключение

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

Восстановление и повторное включение

Процесс ручного повторного включения

Шаги для повторного включения:

1. Определите первопричину, используя историю вызовов
2. Устраните проблемы эндпоинта (аутентификация, URL, ошибки сервера)
3. Снова включите вебхук в деталях вебхука, изменив настройку статуса
4. Протестируйте вебхук вручную кнопкой тестирования в панели
5. Отслеживайте первые доставки, чтобы подтвердить решение

Стратегии профилактики

Избежать автоотключения:

• Реализуйте надлежащую обработку ошибок в своём эндпоинте
• Возвращайте подходящие коды состояния HTTP
• Проактивно отслеживайте состояние вебхука
• Настройте оповещения о сбоях вебхука
• Тестируйте изменения в разработке перед продакшеном

Управление квотой

Вы можете видеть своё использование на графике в панели. Учтите, что использование фиксируется с задержкой.

Неудачные запросы учитываются в квоте

Важно: Все попытки доставки вебхука учитываются в квоте вашей подписки, включая неудачные доставки.

Что учитывается:

• Первоначальные попытки доставки - учитываются в квоте
• Все попытки повтора - каждый повтор учитывается отдельно
• Неудачные доставки - всё равно расходуют квоту
• Тестовые запросы вебхука - также учитываются в квоте

Пример влияния на квоту:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

Эффективное управление квотой

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

• Быстро устраняйте проблемы эндпоинта, чтобы минимизировать неудачные повторы
• Отслеживайте историю вызовов на предмет закономерностей сбоев
• Тщательно тестируйте перед включением вебхуков в продакшене
• Используйте надлежащую обработку ошибок для возврата корректных кодов состояния

Защита квоты: Функция автоотключения помогает предотвратить расход квоты, прекращая доставки на постоянно сбоящие эндпоинты.

Рекомендации по настройке вебхуков см. в основной документации по вебхукам. По тестированию и отладке см. руководство по тестированию.