Перейти к содержимому

Вебхуки

После настройки URL вебхука ваш сервер получает уведомление о завершении задания на перевод файла (/jobs) — независимо от того, завершилось ли оно успешно. Задания, отменённые с помощью POST /jobs/{id}/cancel, не вызывают обратного вызова. Для операций с документами и медиазаданий следует опрашивать соответствующие конечные точки запросов.

Управляется через API, до 3 штук на пользователя:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /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-url
Content-Type: application/json
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 1782900150
X-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 hashlib
import hmac
import json
import 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 отображает время последнего срабатывания каждого вебхука, код состояния и количество последовательных сбоев