При обробці великих обсягів документів синхронні 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 обробляє його асинхронно. Це забезпечує надійність навіть при піковому навантаженні.