Надёжный приём webhook и дедупликация
Версия 2.7
Момент подтверждения доставки
После проверки подписи надёжно запишите событие в очередь, затем ответьте 2xx. Такой порядок отделяет получение события от выполнения бизнес-операции. Если вернуть 2xx до записи, сбой процесса может оставить отправителя с успешным ответом, а получателя без сохранённого события. Проверьте, что очередь подтверждает запись с уровнем надёжности, достаточным для восстановления после остановки процесса.
Хранение ключа дедупликации
Повторы одного события содержат тот же event_id. Используйте его как ключ дедупликации, а при обслуживании нескольких сред или организаций добавьте эти границы в локальный ключ. Операции проверки и вставки должны быть согласованы: две реплики могут получить одну доставку одновременно. Например, добавьте ограничение уникальности в таблицу приёма и проверяйте исход вставки перед созданием новой работы.
Частичный сбой приёма
Если запись в очередь не подтверждена, клиент не должен сообщать об успешном приёме. Если запись прошла, но ответ не дошёл, следующая попытка с тем же event_id должна распознать уже сохранённое событие и не запускать обработку повторно. Проверьте оба случая, включая падение процесса сразу после записи, чтобы воспроизведение отражало фактическую границу между сетью и хранилищем.
Повторы и внутренние задержки
Если обработчик не вернул 2xx, RouteDesk повторяет доставку до 8 раз в течение 24 часов. После успешной доставки повторная бизнес-обработка относится к вашей очереди. Привяжите её к тому же событию и фиксируйте конечный эффект. Для задач, завершившихся ошибкой, храните отдельное состояние и причину, чтобы дежурный мог обработать конкретный сбой без повторного приёма всей партии.
Проверка на тестовых событиях
Отправьте тестовое событие дважды через штатную границу приёма. Проверьте, что появилось ровно одно внутреннее задание и одно ожидаемое изменение локальной записи. Затем остановите обработчик после сохранения события и перезапустите его. Сопоставьте журнал входящих доставок, запись очереди и обновление заказа. В итог проверки включите event_id, число доставок, число записанных задач и число бизнес-изменений.
Срок хранения отметок приёма
Учитывайте окно повторной доставки и собственные сроки восстановления очереди при выборе хранения ключей. Если локальная отметка удаляется раньше повторной попытки, обработчик может принять её за новое событие. Периодически проверяйте очистку на записи, которая всё ещё ожидает бизнес-обработки. Сроки хранения полезно записать в инструкцию дежурного.
Перегрузка входящего обработчика
При росте потока следите за скоростью подтверждения записи и возрастом задач. Оцените, растёт ли очередь из-за временного всплеска или зависшего потребителя. Если приём сохраняет события корректно, восстановите потребителя и проверяйте эффекты на уже принятых event_id. Подтверждённые события не требуется повторно отправлять из источника.