# Referencia de la API de Webhooks — URLs de Callback y Secretos

> Registre o actualice la URL de callback de finalización para un lote y obtenga su secreto de firma: la referencia de Webhooks de la API v1 de ImageToTable.ai.

Registre una URL que se llamará cuando un lote termine de procesarse, en lugar de consultar [Obtener estado del lote](/developers/reference/batches#get-batch-status). 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](/developers/guides/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](/developers/guides/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](/developers/guides/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](/developers/reference/batches#start-processing-a-batch) 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.

`PUT /api/v1/batches/{batch_name}/webhook`

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| batch_name | ruta | string | El lote al que adjuntar esta devolución de llamada. No es necesario que ya tenga documentos cargados; puede registrar un webhook antes de la carga. |
| 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 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](/developers/reference/batches#start-processing-a-batch) 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](/developers/guides/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:

```json
{
  "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](/developers/guides/bbox) activado en cualquier documento de este lote:

```json
{
  "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](/developers/guides/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](/developers/guides/errors).
- `missing_parameter` (`param: "callback_url"`)
- `invalid_parameter` (`param: "callback_url"`) — no es una URL `http://`/`https://`.
- `invalid_parameter` (`param: "batch_name"`)

## Code Examples

### Registrar un webhook de lote

PUT /api/v1/batches/{batch_name}/webhook

**cURL**

```bash
curl -X PUT https://imagetotable.ai/api/v1/batches/july-invoices/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://example.com/webhooks/imagetotable"}'
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://imagetotable.ai/api/v1/batches/july-invoices/webhook",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"callback_url": "https://example.com/webhooks/imagetotable"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/webhook", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ callback_url: "https://example.com/webhooks/imagetotable" }),
});
console.log(await response.json());
```

### Respuesta

```json
{
  "batch_name": "july-invoices",
  "callback_url": "https://example.com/webhooks/imagetotable",
  "webhook_secret": "9f2c1e6a4b8d0f37c5a2e9d1b6f4038a7c1e5d29b4f81c62",
  "created_at": "2026-07-16T09:00:00+00:00",
  "fired_at": null
}
```

`webhook_secret` permanece igual en llamadas repetidas a este endpoint para el mismo `batch_name` — solo se genera una vez, en el primer registro. `fired_at` cambia de `null` a una marca de tiempo la primera (y única) vez que se entrega la notificación de finalización de este lote.

---

Source: https://imagetotable.ai/es/developers/reference/webhooks