Webhooks
Registre una URL para que se le llame cuando un lote termine de procesarse, o liste el feed de eventos persistido para integraciones de sondeo como disparadores de Zapier. Para conocer la forma del payload de devolución de llamada, los tres encabezados de firma y el programa de reintentos, consulte la guía de Webhooks — incluyendo cómo reprocesar 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 acción alguna en este endpoint.
No hay un registro separado para la finalización de bbox. La misma 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 de bbox.
Registrar un webhook de lote
Crea o actualiza el callback 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 registrarlo (o cambiarlo) por separado, por ejemplo, antes de estar listo para llamar a process, o para corregir una URL mal escrita después.
Parámetros
| Nombre | Ubicación | Tipo | Descripción |
|---|---|---|---|
batch_name | ruta | string | El lote al que se adjunta este callback. No es necesario que ya tenga documentos cargados: puede registrar un webhook antes de cargar. |
callback_url | cuerpo (JSON) | string | Obligatorio. Debe ser http:// o https://. Se llama una vez, cuando cada documento del lote alcanza un estado terminal. |
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 el mismo callback_url es la forma admitida de recuperar su secreto nuevamente si lo pierde. Actualizar un registro existente solo afecta a callback_url: webhook_secret nunca se rota con esta llamada, y fired_at (si la ola más reciente de procesamiento de este lote ya le ha notificado) nunca se restablece con esta llamada. Re-armar fired_at para una nueva ola ocurre en Iniciar procesamiento de un lote en su lugar, automáticamente, 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" de la guía de Webhooks. Volver a hacer PUT en este endpoint no le notificará por sí solo nuevamente.
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; estas son las que recibe su servidor.
batch.completed — se dispara 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 dispara cuando un trabajo de anotación bbox activado en cualquier documento de este lote finaliza:
{
"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 en sí — llame a GET /batches/{batch_name}/results o GET /documents/{document_id}/bbox después de 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 bbox) alcanzan un estado terminal en cuestión de momentos entre sí — consulte la guía de Webhooks para los encabezados de firma y el programa de reintentos.
Listar eventos
Devuelve un feed de eventos persistente, del más reciente al más antiguo, para integraciones de sondeo. Este es el endpoint adecuado para disparadores de sondeo de Zapier como "Nuevo lote completado", "Nuevo documento completado" y "Extracción fallida" — no requiere que los usuarios ingresen manualmente un batch_name en el disparador.
Parámetros
| Nombre | Ubicación | Tipo | Descripción |
|---|---|---|---|
type | consulta, opcional | string | Uno de batch.completed, document.completed, document.failed. |
limit | consulta, opcional | integer | 1-100. Valor predeterminado: 20. |
page_token | consulta, opcional | string | Cursor opaco de next_page_token de una respuesta anterior. |
batch_name | consulta, opcional | string | Restringe los eventos a un lote. |
document_id | consulta, opcional | string | Restringe los eventos a un documento. |
created_from | consulta, opcional | datetime | Devuelve eventos creados en o después de esta marca de tiempo ISO 8601. |
created_to | consulta, opcional | datetime | Devuelve eventos creados en o antes de esta marca de tiempo ISO 8601. |
Los eventos se crean solo después de que el trabajador haya confirmado el estado final del documento, por lo que cuando un evento aparece aquí, sus destinos document_url, batch_url y batch_results_url son seguros de leer. Use id como clave de deduplicación. Si un documento fallido se reprocesa y alcanza un estado final nuevamente, o un lote completado recibe otra ola procesada, la nueva finalización recibe un nuevo id de evento.
Posibles errores
missing_api_key/invalid_api_key/plan_required— consulte Manejo de errores.invalid_parameter—type,limit,page_token,batch_name,created_fromocreated_tono válidos.
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 URLhttp:///https://.invalid_parameter(param: "batch_name")