Чеклист надёжности вебхуков: повторные попытки, идемпотентность и повторная обработка

Почему вебхуки кажутся ненадёжными в реальных проектах

Вебхук — простая вещь: одна система отправляет HTTP‑запрос другой системе, когда что‑то происходит. «Заказ отправлен», «тикет обновлён», «устройство ушло в офлайн». По сути это push‑уведомление между приложениями, доставляемое по вебу.

В демо всё кажется надёжным, потому что счастливый путь быстрый и чистый. В реальной работе вебхуки оказываются между системами, которыми вы не управляете: CRM, перевозчики, сервисы поддержки, маркетинговые инструменты, IoT‑платформы и даже внутренние приложения других команд. За исключением платёжных систем вы часто теряете зрелые гарантии доставки, стабильные схемы событий и предсказуемое поведение ретраев.

Первые признаки обычно путают:

• Дубликаты событий (одно и то же обновление приходит дважды)
• Пропущенные события (что‑то изменилось, а вы об этом не узнали)
• Задержки (обновление приходит через минуты или часы)
• Неправильный порядок событий («закрыто» пришло до «открыто»)

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

Представьте перевозчика, который отправляет вебхуки «доставлено». В один день ваш приёмник работает медленно 3 секунды, поэтому они ретраят. Вы получаете две доставки, клиенту уходят два письма, служба поддержки в замешательстве. На следующий день у них простой и они не ретраят вообще — «доставлено» никогда не приходит, и ваша панель зависает.

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

Три строительных блока: ретраи, идемпотентность, replay

Вебхуки идут в двух направлениях. Входящие вебхуки — это вызовы, которые вы принимаете от кого‑то (провайдер платежей, CRM, перевозчик). Исходящие вебхуки — это вызовы, которые вы отправляете вашему клиенту или партнёру при изменениях в вашей системе. Оба типа могут падать по причинам, не связанным с вашим кодом.

Ретраи — это то, что происходит после ошибки. Отправитель может повторить попытку из‑за тайм‑аута, ошибки 500, оборванного соединения или отсутствия ответа в разумный срок. Хорошие ретраи — ожидаемое поведение, а не редкий кейс. Цель — доставить событие, не перегружая приёмник и не создавая побочных эффектов дважды.

Идемпотентность — это способ сделать дубликаты безопасными. Это значит «выполни один раз, даже если получаешь несколько раз». Если тот же вебхук приходит снова, вы определяете это и возвращаете успех, не выполняя бизнес‑действие повторно (например, не создавайте второй счёт).

Replay — ваша кнопка восстановления. Это возможность намеренно повторно обработать прошлые события в контролируемом виде, после исправления бага или после простоя партнёра. Replay отличается от ретраев: ретраи автоматические и немедленные, replay — преднамеренный и часто происходит через часы или дни.

Если вы хотите надёжность вебхуков, задайте простые цели и проектируйте под них:

• Никаких потерянных событий (всегда можно найти то, что пришло или что вы пытались отправить)
• Безопасные дубликаты (ретраи и replay не приводят к двойным списаниям, двойным созданиям или двойным письмам)
• Ясный аудит‑трейл (вы быстро отвечаете «что произошло?»)

Практичный путь поддержать все три — сохранять каждую попытку вебхука с статусом и уникальным идемпотентным ключом. Многие команды строят для этого небольшую таблицу «inbox/outbox» для вебхуков.

Входящие вебхуки: поток приёма, который можно переиспользовать

Большинство проблем с вебхуками происходит потому, что отправитель и приёмник работают на разных часах. Ваша задача как приёмника — быть предсказуемым: подтверждайте быстро, записывайте то, что пришло, и обрабатывайте безопасно.

Разделите «принять» и «выполнить работу»

Начните с потока, который делает HTTP‑запрос быстрым и переносит реальную работу в другое место. Это уменьшает тайм‑ауты и делает ретраи менее болезненными.

• Подтверждайте быстро. Возвращайте 2xx, как только запрос выглядит приемлемым.
• Проверьте базовые вещи. Валидируйте content‑type, обязательные поля и парсинг. Если вебхук подписан, проверьте подпись здесь.
• Сохраните raw‑событие. Запишите тело и заголовки, которые понадобятся позже (подпись, event ID), вместе с отметкой времени получения и статусом вроде «received».
• Поместите работу в очередь. Создайте задачу для фоновой обработки и затем верните 2xx.
• Обрабатывайте с явными исходами. Отмечайте событие как «processed» только после успешных побочных эффектов. Если обработка упала, запишите причину и нужно ли повторить.

Что значит «ответить быстро»

Реалистичная цель — ответить менее чем за секунду. Если отправитель ждёт конкретный код, используйте его (многие принимают 200, некоторые предпочитают 202). Возвращайте 4xx только когда отправителю не стоит пытаться снова (например, неверная подпись).

Пример: customer.created приходит, когда база перегружена. С таким потоком вы всё равно сохраняете raw‑событие, помещаете в очередь и отвечаете 2xx. Ваш воркер позже может повторить обработку без участия отправителя.

Безопасные проверки на приёме, которые не ломают доставку

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

Начните с подтверждения отправителя. Предпочтительны подписанные запросы (HMAC в заголовке) или общий секрет в заголовке. Проверяйте его до тяжёлой работы и быстро отказывайте, если он отсутствует или неверен.

Будьте осторожны со статус‑кодами, потому что они управляют ретраями:

• Возвращайте 401/403 при ошибках аутентификации, чтобы отправитель не ретраил бесконечно.
• Возвращайте 400 при некорректном JSON или отсутствии обязательных полей.
• Возвращайте 5xx только когда ваш сервис временно не может принять или обработать.

IP‑вайтлисты помогают, но только если у провайдера стабильные документированные диапазоны IP. Если их IP часто меняются (или они используют большой пул облака), allowlist может тихо отбрасывать реальные вебхуки, и вы заметите это слишком поздно.

Если провайдер включает временную метку и уникальный event ID, вы можете добавить защиту от replay: отклонять слишком старые сообщения и отслеживать недавние ID для выявления дубликатов. Держите окно времени небольшим, но с запасом, чтобы сдвиг часов не ломал валидные запросы.

Чеклист дружелюбного приёмника:

• Валидируйте подпись или общий секрет до парсинга больших полезных нагрузок.
• Устанавливайте максимум размера тела и короткий тайм‑аут на запрос.
• Используйте 401/403 для ошибок аутентификации, 400 для некорректного JSON и 2xx для принятия событий.
• Если проверяете временные метки, давайте небольшую границу (например, несколько минут).

Для логирования сохраняйте аудит‑трейл без вечного хранения чувствительных данных. Храните event ID, имя отправителя, время получения, результат проверки и хеш raw‑тела. Если вам нужно хранить полезную нагрузку — добавьте политику хранения и маскируйте поля вроде email, токенов или платёжных данных.

Ретраи, которые помогают, а не вредят

Ретраи полезны, когда кратковременная проблема превращается в успешную доставку. Они вредны, когда умножают трафик, скрывают реальные баги или создают дубликаты. Разница — в чётком правиле, что ретраить, как растягивать попытки и когда остановиться.

В качестве базовой модели ретрайте только по причинам, по которым приёмник, скорее всего, сможет принять позже. Полезная ментальная модель: ретрайте при «временных» ошибках, не ретрайте, если «вы отправили что‑то неверно».

Практические HTTP‑исходы:

• Ретрай: сетевые тайм‑ауты, ошибки соединения и HTTP 408, 429, 500, 502, 503, 504
• Не ретрай: HTTP 400, 401, 403, 404, 422
• Зависит: HTTP 409 (иногда «дубликат», иногда реальный конфликт)

Важна пауза между попытками. Используйте экспоненциальный backoff с джиттером, чтобы не создать поток ретраев, когда многие события падают одновременно. Например: 5 с, 15 с, 45 с, 2 мин, 5 мин, с небольшим случайным смещением каждый раз.

Также задайте максимальное окно ретраев и понятную отсечку. Частые варианты: «пытаться в течение 24 часов» или «не более 10 попыток». После этого воспринимайте ситуацию как проблему восстановления, а не доставки.

Чтобы это работало в повседневности, запись события должна содержать:

• Количество попыток
• Последняя ошибка
• Время следующей попытки
• Финальный статус (включая dead‑letter, когда вы прекращаете ретраить)

Элементы в dead‑letter должны быть просты для инспекции и безопасны для повторного запуска после исправления проблемы.

Идемпотентные паттерны, которые работают на практике

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

Выберите ключ, который остаётся стабильным

Если провайдер даёт event ID — используйте его. Это самый чистый вариант.

Если event ID отсутствует, строьте ключ из стабильных полей, например хеш от:

• имя провайдера + тип события + id ресурса + временная метка, или
• имя провайдера + message ID

Сохраняйте ключ с небольшой метаинформацией (время получения, провайдер, тип события и результат).

Правила, которые обычно выдерживают проверку:

• Считайте ключ обязательным. Если не можете его построить, поместите событие в карантин вместо угадывания.
• Храните ключи с TTL (например, 7–30 дней), чтобы таблица не разрасталась бесконечно.
• Сохраняйте результат обработки (success, failed, ignored), чтобы дубликаты получали согласованный ответ.
• Добавьте уникальное ограничение на ключ, чтобы параллельные запросы не запустили работу дважды.

Сделайте бизнес‑действие идемпотентным тоже

Даже при хорошей таблице ключей ваши реальные операции должны быть безопасны. Пример: вебхук «create order» не должен создавать второй заказ, если первая попытка тайм‑аутнулась после вставки в базу. Используйте натуральные бизнес‑идентификаторы (external_order_id, external_user_id) и паттерны upsert.

События вне порядка — частая вещь. Если вы получили «user_updated» до «user_created», установите правило вроде «применяй изменения только если event_version новее» или «обновляй, только если updated_at позже того, что у нас есть».

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

• Если ключ совпадает, но payload отличается — считайте это багом провайдера и тревожьте команду.
• Если ключ совпадает, а payload отличается лишь в несущественных полях — игнорируйте изменения.
• Если провайдера нельзя доверять, переходите на ключ, основанный на хеше полного payload, и обрабатывайте конфликты как новые события.

Цель проста: одно реальное изменение в мире должно давать один реальный результат, даже если вы получаете сообщение трижды.

Инструменты replay и журналы аудита для восстановления

Когда у партнёра проблемы, надёжность — это не идеальная доставка, а быстрая способность восстановиться. Инструмент replay превращает «мы потеряли события» в рутинную фиксацию, а не кризис.

Начните с журнала событий, который отслеживает жизненный цикл каждого вебхука: received, processed, failed или ignored. Делайте его доступным для поиска по времени, типу события и корреляционному ID, чтобы служба поддержки могла быстро ответить «Что произошло с заказом 18432?».

Для каждого события храните контекст, достаточный для повторного запуска того же решения:

• raw‑payload и ключевые заголовки (подпись, event ID, timestamp)
• нормализованные поля, которые вы извлекли
• результат обработки и сообщение об ошибке (если есть)
• версия workflow или маппинга, использованная в момент обработки
• отметки времени получения, начала и окончания

С этим готовым добавьте действие «Replay» для неудачных событий. Кнопка менее важна, чем предохранители. Хороший поток replay показывает предыдущую ошибку, что произойдёт при повторной отправке и безопасно ли её выполнять.

Защитные механизмы, которые предотвращают вред:

• Требовать заметку с причиной перед replay
• Ограничить права на replay небольшой ролью
• Повторно проходить те же идемпотентные проверки, что и при первой попытке
• Ограничивать скорость replay, чтобы не создать новый всплеск во время инцидента
• Опциональный dry‑run режим, который валидирует без записи изменений

Инциденты часто включают несколько событий, поэтому поддерживайте replay по временному диапазону (например, «повторить все неудачные события с 10:05 по 10:40»). Логируйте, кто что и когда повторял и почему.

Исходящие вебхуки: поток отправки, который можно аудировать

Исходящие вебхуки падают по скучным причинам: медленный приёмник, кратковременный простой, сбой DNS или прокси, который обрывает длинные запросы. Надёжность приходит, когда каждую отправку рассматривают как отслеживаемую повторяемую задачу, а не как одноразовый HTTP‑вызов.

Поток отправителя, который остаётся предсказуемым

Дайте каждому событию стабильный уникальный event ID. Этот ID должен оставаться тем же во всех ретраях, replay и перезапусках сервиса. Если вы генерируете новый ID для каждой попытки, вы усложняете дедуп и аудит.

Далее подпишите каждый запрос и добавьте временную метку. Временная метка помогает приёмникам отклонять очень старые запросы, подпись доказывает, что payload не менялся в пути. Делайте правила подписи простыми и последовательными, чтобы партнёру было легко их реализовать.

Отслеживайте доставку по каждому endpoint, а не только по событию. Если вы отправляете одно событие трём адресатам, каждая цель нуждается в собственной истории попыток и финальном статусе.

Практичный поток, который может реализовать большинство команд:

• Создайте запись события с event ID, endpoint ID, хешем payload и стартовым статусом.
• Отправьте HTTP‑запрос с подписью, timestamp и заголовком idempotency key.
• Записывайте каждую попытку (время начала, время окончания, HTTP‑статус, короткое сообщение об ошибке).
• Ретрайте только при тайм‑аутах и 5xx с экспоненциальным backoff и джиттером.
• Остановитесь после понятного лимита (макс попыток или макс возраста) и отметьте событие как требующее проверки.

Этот заголовок idempotency важен даже когда вы отправляете. Он даёт приёмнику простой способ дедупа, если они обработали первый запрос, а клиент не получил 200.

Наконец, делайте ошибки видимыми. «Failed» не должно значить «потеряно». Это должно значить «поставлено на паузу с контекстом, достаточным для безопасного replay».

Пример: нестабильная система партнёра и чистое восстановление

Ваше приложение поддержки отправляет обновления тикетов партнёру, чтобы их агенты видели тот же статус. Каждый раз, когда тикет меняется (назначен, изменён приоритет, закрыт), вы постите вебхук ticket.updated.

Однажды днём endpoint партнёра начинает тайм‑аутить. Ваша первая попытка доставки ждёт, достигает лимита тайм‑аута, и вы маркируете её как «неизвестно» (возможно, они получили, возможно, нет). Хорошая стратегия ретраев будет повторять с backoff, а не слать повторы каждую секунду. Событие остаётся в очереди с тем же event ID, и каждая попытка логируется.

Самая больная часть: если вы не используете идемпотентность, партнёр может обработать дубликаты. Попытка №1 могла дойти до них, но их ответ не вернулся. Попытка №2 приходит позже и создаёт второй «тикет закрыт», отправляет два письма или создаёт два timeline‑записи.

С идемпотентностью каждая доставка включает idempotency key, полученный из события (часто просто event ID). Партнёр хранит этот ключ на некоторое время и отвечает «уже обработано» для повторов. Вы прекращаете угадывать.

Когда партнёр восстановился, replay исправляет реально потерянные обновления (например, изменение приоритета во время простоя). Вы выбираете событие в журнале аудита и повторяете его с тем же payload и idempotency key — это безопасно, даже если они уже его получили.

Во время инцидента ваши логи должны делать картину очевидной:

• Event ID, ticket ID, тип события и версия payload
• Номер попытки, отметки времени и время следующей попытки
• Тайм‑аут против non‑2xx ответа против успеха
• Отправленный idempotency key и сигнал партнёра «duplicate»
• Запись replay: кто повторял и итоговый результат

Частые ошибки и ловушки, которых стоит избегать

Большинство инцидентов с вебхуками не вызваны одной большой ошибкой. Они появляются из маленьких решений, которые тихо разрушают надёжность при всплесках трафика или флаке у третьих сторон.

Ловушки, которые появляются в постмортах:

• Выполнение медленной работы внутри обработчика запроса (записи в БД, вызовы API, загрузки файлов) до тех пор, пока отправитель не тайм‑аутит и не ретраит
• Предположение, что провайдеры никогда не шлют дубликаты, и как результат — двойное списание, двойное создание заказов или два письма
• Возврат неправильных кодов статуса (200, даже если вы не приняли событие, или 500 для «плохих данных», которые никогда не удастся обработать при повторном запросе)
• Деплой без correlation ID, event ID или request ID и затем часы на сопоставление логов с жалобами клиентов
• Бесконечные ретраи, которые накапливают бэклог и превращают простой партнёра в ваш собственный кризис

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

Статусы важнее, чем многие думают:

• Используйте 2xx только когда вы сохранили событие (или поставили в очередь) и уверены, что оно будет обработано.
• Используйте 4xx для неверного ввода или проваленной аутентификации, чтобы отправитель прекратил ретраи.
• Используйте 5xx только для временных проблем на вашей стороне.

Задайте потолок ретраев. Прекратите после фиксированного окна (например, 24 часа) или фиксированного числа попыток, затем пометьте событие как «требует проверки», чтобы человек решил, что реплейнуть.

Короткий чеклист и следующие шаги

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

Быстрые проверки для входящих (приём)

• Возвращайте быстрый 2xx, как только запрос безопасно записан (медленную работу делайте асинхронно).
• Храните достаточно события, чтобы доказать, что вы получили и чтобы отлаживать позже.
• Требуйте идемпотентный ключ (или выводите его из provider + event ID) и принудительно храните его в БД.
• Используйте 4xx для плохой подписи или некорректной схемы, и 5xx только для реальных серверных проблем.
• Отслеживайте статус обработки (received, processed, failed) и последнее сообщение об ошибке.

Быстрые проверки для исходящих (отправитель)

• Назначьте уникальный event ID для каждого события и держите его стабильным между попытками.
• Подписывайте каждый запрос и добавляйте временную метку.
• Определите политику ретраев (backoff, максимум попыток и когда остановиться) и соблюдайте её.
• Отслеживайте состояние по каждому endpoint: последний успех, последний провал, подряд идущие ошибки, время следующей попытки.
• Логируйте каждую попытку с деталями для поддержки и аудита.

Для оперирования заранее решите, что вы будете реплейить (одно событие, пакет по временному диапазону, или и то, и другое), кто может это делать и как выглядит процедура ревью dead‑letter.

Если вы хотите собрать эти элементы без ручной связки каждой детали, no‑code платформа вроде AppMaster (appmaster.io) может подойти: вы моделируете inbox/outbox вебхуков в PostgreSQL, реализуете ретраи и replay в визуальном Business Process Editor и выставляете внутреннюю админку для поиска и повторного запуска неудачных событий, когда партнёры флакируют.