Как сделать обмен по API и webhooks устойчивым к сбоям

API отвечает за запрос, а не за бизнес-результат. Код 200 может означать только прием сообщения, соединение может оборваться после создания объекта, а webhook — прийти дважды или не прийти вовсе. Надежный обмен учитывает эти состояния заранее и позволяет найти судьбу каждой операции.

Сначала сохраните событие

Критичную операцию нельзя держать только в памяти процесса. После действия пользователя или получения webhook событие сохраняют с идентификатором, временем, типом и исходным статусом. Только затем начинается передача.

Это дает возможность:

• повторить операцию;
• увидеть очередь;
• восстановиться после перезапуска;
• связать внутренний и внешний объект;
• провести сверку;
• доказать факт обработки.

Для формы или заказа локальное сохранение также отделяет ответ пользователю от доступности внешней системы.

Используйте очередь

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

У очереди должны быть:

• ограниченное число попыток;
• задержка между повторами;
• защита от параллельной обработки одной операции;
• отдельное место для окончательных ошибок;
• метрика возраста самой старой операции;
• уведомление при росте задержки.

Очередь не исправляет плохой контракт автоматически. Она лишь не дает временной проблеме превратиться в потерю.

Идемпотентность

Если отправитель не получил ответ, он не знает, выполнилась ли операция. Повтор обязателен, но должен быть безопасным.

Каждое событие получает idempotency key. Получатель сохраняет ключ вместе с результатом. При повторе он возвращает прежний результат или обновляет тот же объект, а не создает новый.

Ключ должен относиться к операции, а не к клиенту вообще. Один человек может отправить несколько заявок с одинаковым email.

Разделяйте типы ошибок

Повторяют только временные состояния:

• сетевой таймаут;
• 502, 503, 504;
• ограничение частоты;
• временную блокировку ресурса.

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

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

Webhook не является гарантией доставки

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

Для входящего события проверяют:

1. 1Подпись или секрет источника.
2. 2Временную метку и допустимое окно.
3. 3Уникальный идентификатор.
4. 4Размер и формат сообщения.
5. 5Известную версию схемы.
6. 6Право источника на событие.

После проверки событие сохраняется, а обработчик возвращает ответ. Фактическое изменение системы происходит отдельно.

Защита от подделки и повторного воспроизведения

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

Временная метка и идентификатор защищают от повторного воспроизведения старого запроса. При смене секрета полезен короткий переходный период с поддержкой двух ключей.

Контракт и версия данных

Отправитель и получатель должны одинаково понимать поля. Контракт фиксирует типы, обязательность, допустимые значения и поведение при неизвестном поле.

Безопасное изменение:

• сначала получатель принимает новый формат;
• затем отправитель начинает его передавать;
• после наблюдения старый формат выводится;
• несовместимое изменение получает новую версию.

Принципы карты событий и источника истины подробнее разобраны в статье о проектировании интеграции сайта с CRM.

Журнал операции

Наблюдаемость строится вокруг идентификатора события. В журнале нужны направление, endpoint без секрета, код ответа, длительность, номер попытки и внешний идентификатор.

Полезно различать:

• событие создано;
• принято транспортом;
• прошло валидацию;
• применено к данным;
• подтверждено внешней системой.

Так команда понимает, на каком шаге остановилась конкретная заявка.

Контрольная сверка

Даже хороший webhook дополняют периодической сверкой. Например, сравнивают количество заказов за период, проверяют незавершенные операции или запрашивают состояние объектов, которые слишком долго остаются в очереди.

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

Мониторинг

Контролировать только доступность API недостаточно. Нужны бизнес-технические сигналы:

• возраст старейшей задачи;
• размер очереди;
• доля ошибок;
• число окончательно остановленных операций;
• время последнего успешного обмена;
• расхождение контрольной сверки.

Практический набор внешних и внутренних проверок описан в статье о мониторинге доступности.

Тестовые сценарии

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

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

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

Можно ли обойтись без очереди?

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

Как долго хранить журнал?

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

Что делать с окончательно ошибочной задачей?

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

Достаточно ли HTTP-кода для контроля?

Нет. Нужен внешний идентификатор или проверка результата. Ответ мог подтвердить только прием, а бизнес-операция завершиться позже с ошибкой.