Webhooks

Registre una URL que se llamará cuando un lote termine de procesarse, en lugar de consultar Obtener estado del lote. Esta página cubre el único endpoint de registro; para la forma del payload, los tres encabezados de firma y el programa de reintentos, consulte la guía de Webhooks — incluyendo cómo el reprocesamiento de un lote (subir y procesar más documentos en un batch_name que ya le notificó una vez) recibe su propia notificación separada automáticamente, sin necesidad de ninguna acción en este endpoint.

No existe un registro separado para la finalización de bbox. El mismo callback_url que registra aquí también recibe un evento document.bbox_completed cada vez que un trabajo de anotación bbox finaliza en cualquier documento de este lote — activar bbox no requiere (ni admite) su propio endpoint de webhook. Consulte la guía de Webhooks para conocer la forma del payload del evento y la advertencia de entrega específica para bbox.

Registrar un webhook de lote

Crea o actualiza la devolución de llamada de finalización para un lote. También puede establecer webhook_url directamente en Iniciar procesamiento de un lote para registrarlo en la misma llamada. Este endpoint existe para registrar (o cambiar) el webhook por separado, por ejemplo, antes de estar listo para llamar a process, o para corregir una URL con errores tipográficos después.

Parámetros

webhook_secret se devuelve en cada respuesta exitosa — tanto en el primer registro como en cada actualización posterior — sin enmascararse después de la primera llamada. No existe un GET separado para este recurso, por lo que volver a hacer PUT con la misma callback_url es la forma recomendada de recuperar su secreto si lo pierde. Al actualizar un registro existente, solo se modifica callback_url: webhook_secret nunca se rota con esta llamada, y fired_at (si la ola de procesamiento más reciente de este lote ya le ha notificado) nunca se reinicia con esta llamada. El restablecimiento de fired_at para una nueva ola ocurre en Iniciar procesamiento de un lote de forma automática, en el momento en que encuentra nuevos documentos elegibles en un lote cuya ola anterior ya se disparó; consulte la sección "Reprocesamiento de un lote" en la guía de Webhooks. Volver a hacer PUT en este endpoint no le notificará de nuevo por sí mismo.

Cargas útiles de eventos entregados

Una vez registrado, callback_url recibe un POST para uno de dos tipos de eventos, distinguidos por el campo "type" de nivel superior — este endpoint nunca devuelve ninguna de las dos formas; estos son los que recibe su servidor.

batch.completed — se activa una vez, cuando cada documento del lote alcanza un estado terminal:

{
  "type": "batch.completed",
  "created_at": "2026-07-16T09:14:31Z",
  "data": {
    "batch_name": "260716-4K9P",
    "status": "succeeded",
    "document_count": 3
  }
}

document.bbox_completed — se activa cuando finaliza un trabajo de anotación de bbox activado en cualquier documento de este lote:

{
  "type": "document.bbox_completed",
  "created_at": "2026-07-16T09:20:07Z",
  "data": {
    "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
    "group_batch_id": "bx_8a3c2e1f",
    "status": "succeeded"
  }
}

Ninguna carga útil incluye los resultados extraídos — llame a GET /batches/{batch_name}/results o GET /documents/{document_id}/bbox tras recibir el evento correspondiente para obtener los datos reales. Ambos eventos se entregan como máximo una vez por finalización, incluso cuando varios documentos (o varios grupos de filas de bbox) alcanzan un estado terminal en momentos cercanos — consulte la guía de Webhooks para conocer los encabezados de firma y el programa de reintentos.

Posibles errores

• missing_api_key / invalid_api_key / plan_required — consulte Manejo de Errores.
• missing_parameter (param: "callback_url")
• invalid_parameter (param: "callback_url") — no es una URL http:///https://.
• invalid_parameter (param: "batch_name")