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.
Administrar webhooks
Sección titulada «Administrar webhooks»Administrados a través de la API, hasta 3 por usuario:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteCrear ejemplo:
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).
Formato de devolución de llamada
Sección titulada «Formato de devolución de llamada»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 }}Eventos
Sección titulada «Eventos»| Evento | Cuando |
|---|---|
job.completed | Un 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.
Verifique la firma
Sección titulada «Verifique la firma»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 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 eventLa 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).
Entrega
Sección titulada «Entrega»- El receptor debe devolver
2xxen 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,datay la firma coinciden con la primera entrega; si elsecretcambió en el intervalo, la nuevasecretfirma); 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_idydata.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
PATCHuna vez que se haya solucionado el problema del receptor. GET /api/v1/webhooksmuestra la última hora de activación, el código de estado y los fallos consecutivos de cada webhook