Вебгінки
Після налаштування URL-адреси вебгілки ваш сервер отримує повідомлення, коли завершується завдання перекладу файлу (/jobs) — незалежно від успішності. Завдання, скасовані за допомогою POST /jobs/{id}/cancel, не викликають зворотного виклику. Для операцій із документами та медіазавдань слід запитувати статус через їхні власні кінцеві точки запитів.
Керування вебгуками
Section titled “Керування вебгуками”Керується через API, максимум 3 на користувача:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteСтворіть приклад:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'URL має бути доступним з публічного Інтернету, бажано через HTTPS; приватні мережі, локальні адреси та некоректні URL повертають 400. Запит PATCH може змінювати url, secret, events, description та status (active / disabled).
Формат зворотного виклику
Section titled “Формат зворотного виклику”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}| Подія | Коли |
|---|---|
job.completed | Робота завершується; data.status становить completed або failed |
Невдалі завдання також використовують подію job.completed; розрізняйте їх за допомогою data.status == "failed" та необов’язкового data.error. Успішні завдання не містять поля error. data.char_count — це кількість символів у перекладі, 0 — для невдалих завдань.
events приймає лише job.completed та * (усі події); інші значення або порожній список повертають 422. У запиті PATCH залишайте поля, які не змінюєте; надсилання null також повертає 422.
Перевірте підпис
Section titled “Перевірте підпис”Коли ви налаштовуєте secret для вебгіка, кожен зворотний виклик містить X-Webhook-Signature. Перевірте це за допомогою HMAC-SHA256 у вихідному тілі запиту raw request body :
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return eventПідпис охоплює лише тіло повідомлення, а не заголовки. Для захисту від повторних спроб перевірте timestamp у тілі після успішного проходження підпису (він дорівнює X-Webhook-Timestamp, але підписується лише значення тіла), а також здійсніть дедуплікацію за допомогою data.job_id і data.status. При повторних спробах тіло першого надсилання відправляється без змін, з таким самим timestamp, а остання повторна спроба надходить приблизно через 8,6 години після першого надсилання, тому не робіть це вікно коротшим за цей проміжок (у прикладі використовується 12 годин).
Доставка
Section titled “Доставка”- Одержувач має повернути
2xxпротягом 15 секунд, щоб доставку зарахувати як успішну; перенаправлення не обробляються. - Невдалі спроби доставки (через таймаут, помилку з’єднання або код помилки
2xx) автоматично повторюються: через 1 хвилину, 5 хвилин, 30 хвилин, 2 години та 6 годин після попередньої невдачі; максимум 6 спроб доставки на кожну подію, після чого повторні спроби не здійснюються. - Повторні спроби надсилаються на поточний URL гейвебука з незмінним телом (
timestamp,dataі підпис відповідає першій доставці; якщо між цим змінивсяsecret, то підписують новимsecret); події, які вже були доставлені, не надсилаються повторно. - Коли вебгук вимкнено, видалено або припинено підписку на подію, його очікувані повторні спроби скасовуються.
- Слідники мають обробляти події ідемпотентно згідно з
data.job_idтаdata.statusі швидко реагувати після їх безпечного збереження. - Кілька вебгуків одного облікового запису доставляються паралельно; повільний отримувач не затримує інші.
- Після 10 послідовних невдалих спроб доставки (включаючи повторні спроби) вебгук автоматично вимикається; після усунення проблеми на стороні отримувача його можна знову активувати за допомогою
PATCH GET /api/v1/webhooksвідображає час останнього запуску, код стану та кількість послідовних помилок кожного вебгіка