Webhooks

Recibe notificaciones HTTP en tu servidor cuando un documento o una extracción llega a un estado final. Evitan el polling continuo: haces POST del documento, y la plataforma te avisa cuando hay resultado.

Configuración

La URL del webhook se configura por ambiente desde el panel de administración (no vía API). Al guardarla se genera un secreto de firma que se muestra una sola vez — guárdalo en tu servidor como variable de entorno. Puedes regenerarlo desde el mismo panel.

Requisitos de la URL:

https:// obligatorio en producción.
No puede apuntar a localhost ni a IPs privadas.
No se siguen redirects.

Eventos

Evento	Cuándo se envía
`document.completed`	OCR terminado con éxito.
`document.partial_success`	OCR terminado con resultados parciales.
`document.failed`	OCR falló.
`extraction.completed`	Extracción LLM completada y validada.
`extraction.failed`	Extracción falló (proveedor, input, etc.).
`extraction.validation_failed`	La respuesta del LLM no cumplió el schema solicitado.

Payload

POST https://tu-servidor.com/webhooks/ocr
Content-Type: application/json
X-Webhook-Event: extraction.completed
X-Signature: sha256=3f5a1c...

{
  "event": "extraction.completed",
  "extraction_id": "ext_xxxxxxxxxxxxxxxxxxxxxxxx",
  "document_id": "doc_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "timestamp": "2026-07-02T17:48:21+00:00",
  "delivery_id": "whd_xxxxxxxxxxxxxxxxxxxxxxxx"
}

Los eventos document.* no incluyen extraction_id. El payload no incluye el resultado: al recibir el evento, consulta el resultado por API: GET /extractions/{id}/result para extracciones o GET /documents/{id}/result?format=... para OCR. Ante *.failed o extraction.validation_failed, consulta GET /extractions/{id} o GET /documents/{id} para ver failure.

Verificación de firma

Cada entrega se firma con HMAC-SHA256 sobre el body crudo usando tu secreto. Verifica siempre antes de procesar:

$esperada = 'sha256='.hash_hmac('sha256', $request->getContent(), $secret);

if (! hash_equals($esperada, (string) $request->header('X-Signature'))) {
    abort(401);
}

Usa el body crudo tal como llega. Si lo re-serializas (decode + encode), la firma no coincidirá.

Entrega y reintentos

Tu endpoint debe responder 2xx en menos de 10 segundos. Responde rápido y procesa después (encola el trabajo).
Cualquier otra respuesta o timeout cuenta como fallo. Se hacen hasta 5 intentos en total (el envío original más 4 reintentos a los 30 s, 2 min, 10 min y 1 h).
delivery_id es único por entrega — úsalo para deduplicar si recibes la misma entrega más de una vez.
El orden de llegada no está garantizado; usa timestamp si necesitas ordenar.

Probar sin servidor propio

La plataforma expone un receptor de prueba: configura como URL del webhook

https://ocr.789.com.mx/webhook-test

Cada entrega recibida queda en el log interno de la plataforma con el evento, el payload y si la firma fue válida (signature_valid: true). Tú no tienes acceso a ese log: pide al equipo de plataforma que confirme las entregas. Para ver los payloads tú mismo, apunta el webhook a tu propio endpoint de pruebas.