Надёжная обработка webhook: подпись, повторы, идемпотентность и очередь

Что важно понять до начала

Webhook переносит событие от внешней системы в ваш продукт, но сеть не гарантирует единственную и упорядоченную доставку. Поставщик может повторить запрос после таймаута, а разные события — прийти в неожиданной последовательности.

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

Как закрепить результат

Разовая настройка быстро устаревает. Правила, тесты и владельцы нужны, чтобы качество сохранялось при следующих релизах и новых интеграциях.

• Секреты ротируются без остановки приёма событий.
• Логи содержат event ID и correlation ID, но не раскрывают секреты и лишние данные.
• Очередь и база имеют метрики возраста, повторов и необработанных сообщений.
• Тесты воспроизводят дубликат, неверную подпись, задержку и перестановку событий.

Что подготовить

До изменений зафиксируйте границы задачи, исходные данные, ответственных и критерий готовности. Это делает проверку воспроизводимой и защищает рабочие процессы.

• Изучить схему подписи, политику повторов и уникальный идентификатор события у поставщика.
• Определить допустимую задержку и последствия повторной или пропущенной обработки.
• Подготовить секреты отдельно для тестового и рабочего окружений.
• Описать процедуру ручного повторного запуска и восстановления из журнала.

Пошаговый план

Работайте небольшими проверяемыми этапами: каждый шаг должен оставлять наблюдаемый результат, который можно проверить до выпуска и после него.

• Получить исходное тело запроса и проверить подпись до разбора доверенных полей.
• Проверить временную метку и защититься от повторного воспроизведения старого запроса.
• Сохранить ID события с уникальным ограничением и исходным статусом обработки.
• Поместить подтверждённое событие в очередь и быстро вернуть поставщику 2xx.
• Выполнять бизнес-операцию идемпотентно и фиксировать результат атомарно.
• Настроить повторы с backoff, dead-letter очередь, алерты и инструмент replay.

Что измерять

Набор метрик должен одновременно показывать техническое качество, пользовательский результат и скорость реакции команды на отклонение.

• Доля событий, подтверждённых в пределах SLA поставщика.
• Количество дубликатов и доля безопасно подавленных повторов.
• Возраст самого старого сообщения и размер очереди.
• Число событий в dead-letter очереди и время восстановления.

Типичные ошибки

Большинство сбоев возникает на границах ответственности: когда техническая проверка не связана с бизнес-сценарием, данными и действиями пользователя.

• Запускать долгую бизнес-логику до ответа поставщику.
• Считать повторную доставку ошибкой поставщика и не делать операцию идемпотентной.
• Разбирать изменённое middleware тело при проверке криптографической подписи.
• Возвращать 200 до надёжного сохранения события, теряя возможность восстановления.

Результат работы

Webhook нужно проектировать как доставку минимум один раз: один и тот же факт может прийти повторно, позже или не по порядку.

Готовое решение включает не только исправление или настройку, но и документированный способ повторной проверки. Так команда может безопасно развивать продукт без возврата прежней проблемы.