Вебхуки
После настройки URL вебхука ваш сервер получает уведомление о завершении задания на перевод файла (/jobs) — независимо от того, завершилось ли оно успешно. Задания, отменённые с помощью POST /jobs/{id}/cancel, не вызывают обратного вызова. Для операций с документами и медиазаданий следует опрашивать соответствующие конечные точки запросов.
Управление вебхуками
Заголовок раздела «Управление вебхуками»Управляется через 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).
Формат обратного вызова
Заголовок раздела «Формат обратного вызова»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.
Проверьте подпись
Заголовок раздела «Проверьте подпись»Когда вы устанавливаете 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 часов).
Доставка
Заголовок раздела «Доставка»- Получатель должен вернуть
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отображает время последнего срабатывания каждого вебхука, код состояния и количество последовательных сбоев