Saltearse al contenido

Webhooks

Con una URL de webhook configurada, su servidor recibe una notificación cuando finaliza un trabajo de traducción de archivos (/jobs) (con éxito o no). Los trabajos cancelados con POST /jobs/{id}/cancel no envían ninguna llamada de retorno. Para las operaciones de documentos y los trabajos multimedia, consulte sus propios puntos de consulta.

Administrados a través de la API, hasta 3 por usuario:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /api/v1/webhooks/{id} delete

Crear ejemplo:

Ventana de terminal
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"
}'

La URL debe ser accesible desde Internet público, preferiblemente a través de HTTPS; las redes privadas, las direcciones locales y las URLs malformadas devuelven 400. PATCH puede modificar url, secret, events, description y 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
}
}
EventoCuando
job.completedUn trabajo finaliza; data.status es completed o failed

Los trabajos fallidos también utilizan el evento job.completed; diferéncielos mediante data.status == "failed" y el opcional data.error. Los trabajos exitosos no incluyen el campo error. data.char_count es el número de caracteres en la traducción, 0 para los trabajos fallidos.

events acepta únicamente job.completed y * (todos los eventos); otros valores o una lista vacía devuelven 422. En una solicitud PATCH, omita los campos que no vaya a modificar; enviar null también devuelve 422.

Cuando configuras un secret en el webhook, cada devolución de llamada incluye X-Webhook-Signature. Verifícalo con HMAC-SHA256 en el cuerpo de la solicitud sin procesar 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

La firma cubre únicamente el cuerpo, no los encabezados. Para la protección contra reproducciones, verifique timestamp en el cuerpo una vez que la firma haya sido validada (equivale a X-Webhook-Timestamp, pero solo se firma el valor del cuerpo), y deduplique mediante data.job_id y data.status. Los reintentos reenvían el cuerpo de la primera entrega sin cambios, con el mismo timestamp, y el último intento se produce aproximadamente 8,6 horas después de la primera entrega; por lo tanto, no reduzca ese intervalo de tiempo por debajo de ese valor (en el ejemplo se utiliza un plazo de 12 horas).

  • El receptor debe devolver 2xx en un plazo de 15 segundos para que la entrega se considere exitosa; no se siguen las redirecciones.
  • Las entregas fallidas (por tiempo de espera, error de conexión o no 2xx) se reintentan automáticamente: 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas después del fallo anterior; como máximo, 6 intentos por evento, y luego no se realizarán más.
  • Los reintentos se envían a la URL actual del webhook con el cuerpo sin cambios (timestamp, data y la firma coinciden con la primera entrega; si el secret cambió en el intervalo, la nueva secret firma); los eventos ya entregados no se vuelven a enviar
  • Cuando un webhook está deshabilitado, eliminado o ya no está suscrito al evento, sus reintentos pendientes se cancelan.
  • Los receptores deben procesar los eventos de forma idempotente según data.job_id y data.status, y responder rápidamente tras persistirlos de manera segura.
  • Los múltiples webhooks de una misma cuenta se entregan en paralelo; un receptor lento no ralentiza a los demás.
  • Tras 10 entregas fallidas consecutivas (incluidos los intentos de reenvío), el webhook se desactiva automáticamente; vuelva a habilitarlo con PATCH una vez que se haya solucionado el problema del receptor.
  • GET /api/v1/webhooks muestra la última hora de activación, el código de estado y los fallos consecutivos de cada webhook