Webhooks Best Practices: Reliable Async Document Processing

При обробці великих обсягів документів синхронні API-виклики стають вузьким місцем. Webhook-и дозволяють будувати надійні асинхронні pipeline-и, де ви відправляєте документ і отримуєте результат, коли він готовий.

Налаштування Webhook endpoint

Ваш endpoint повинен відповідати на POST-запити та повертати HTTP 200 протягом 5 секунд. Якщо ми не отримуємо підтвердження, запит буде повторено з exponential backoff: через 30 секунд, 2 хвилини, 10 хвилин.

Верифікація підписів HMAC-SHA256

Кожен webhook містить заголовок X-Rekognita-Signature з HMAC-SHA256 підписом тіла запиту. Завжди перевіряйте підпис перед обробкою даних — це захищає від підроблених запитів.

Ідемпотентність

Webhook може бути доставлений більше одного разу (at-least-once delivery). Використовуйте поле event_id для дедуплікації. Зберігайте оброблені event_id в базі даних або Redis і пропускайте повторні запити.

Error Handling

Якщо обробка документа завершилась помилкою, webhook містить поле error з описом проблеми. Типові помилки: файл пошкоджений, формат не підтримується, перевищено ліміт розміру. Логуйте ці помилки та налаштуйте алерти для моніторингу.

Приклад архітектури

Рекомендована архітектура: API Gateway → Queue (SQS/RabbitMQ) → Worker. Webhook endpoint тільки валідує підпис та кладе повідомлення в чергу, а worker обробляє його асинхронно. Це забезпечує надійність навіть при піковому навантаженні.