Идемпотентный запрос
Ключ идемпотентности связывает повторную попытку с тем же намерением. Один и тот же ключ с теми же параметрами возвращает прежний результат, а изменение параметров должно быть отклонено как конфликт.
Статусы не равны HTTP-ответу
Ответ API подтверждает приём запроса, но не завершение фоновой операции. Клиент сохраняет идентификатор операции и обрабатывает переходы вроде queued, running, succeeded и failed согласно контракту.
Webhooks как подсказка
Webhook ускоряет реакцию, но не заменяет источник истины. Обработчик проверяет подпись, принимает повторную доставку, быстро отвечает и ставит событие в очередь. Для итогового состояния выполняется сверка по идентификатору операции.
Порядок и повторная доставка
События могут прийти повторно или с задержкой. Храните обработанные event id, не полагайтесь на порядок доставки и игнорируйте переход назад, если он не разрешён моделью операции.
Безопасная схема
- Создайте ключ на бизнес-операцию.
- Сохраните запрос и идентификатор операции.
- Получайте статус polling или webhook.
- Проверьте финальный состав и SHA-256.
- Запишите результат в журнал интеграции.
Итог
Идемпотентность защищает от дублей, статусы показывают реальный прогресс, а подписанный webhook доставляет сигнал. Только их совместное использование делает автоматизацию предсказуемой.