Webhooks

Registre uma URL para ser chamada quando um lote terminar o processamento, ou liste o feed de eventos persistido para integrações de polling, como gatilhos do Zapier. Para o formato do payload do callback, os três cabeçalhos de assinatura e o cronograma de novas tentativas, consulte o guia de Webhooks — incluindo como reprocessar um lote (enviar e processar mais documentos em um batch_name que já notificou você uma vez) gera sua própria notificação separada automaticamente, sem necessidade de ação neste endpoint.

Não há registro separado para a conclusão de bbox. O mesmo callback_url que você registra aqui também recebe um evento document.bbox_completed sempre que um trabalho de anotação bbox termina em qualquer documento deste lote — acionar bbox não exige (nem suporta) seu próprio endpoint de webhook. Consulte o guia de Webhooks para o formato do payload do evento e a ressalva de entrega específica do bbox.

Registrar um webhook de lote

Cria ou atualiza o callback de conclusão para um lote. Você também pode definir webhook_url diretamente em Iniciar processamento de um lote para registrá-lo na mesma chamada — este endpoint existe para registrar (ou alterar) o callback separadamente, por exemplo, antes de estar pronto para chamar process, ou para corrigir uma URL com erro de digitação depois.

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

Parâmetros

Nome	Local	Tipo	Descrição
`batch_name`	caminho	string	O lote ao qual anexar este callback. Não precisa já ter documentos enviados — você pode registrar um webhook antes do envio.
`callback_url`	corpo (JSON)	string	Obrigatório. Deve ser `http://` ou `https://`. Chamado uma vez, quando cada documento no lote atingir um status final.

webhook_secret é retornado em toda resposta bem-sucedida — no primeiro registro e em toda atualização subsequente — não mascarado após a primeira chamada. Não há um GET separado para este recurso, então reenviar um PUT com o mesmo callback_url é a forma suportada de recuperar seu segredo novamente se você o perder. Atualizar um registro existente apenas altera callback_url: webhook_secret nunca é rotacionado por esta chamada, e fired_at (se a onda mais recente de processamento deste lote já notificou você) nunca é redefinido por esta chamada. Reativar fired_at para uma nova onda acontece em Iniciar processamento de um lote automaticamente, no momento em que encontra novos documentos elegíveis em um lote cuja onda anterior já foi disparada — consulte a seção "Reprocessando um lote" do guia de Webhooks. Reenviar um PUT para este endpoint não faz, por si só, você ser notificado novamente.

Cargas úteis de eventos entregues

Uma vez registrado, o callback_url recebe um POST para um de dois tipos de eventos, distinguidos pelo campo "type" de nível superior — este endpoint em si nunca retorna nenhuma das formas; estes são o que seu servidor recebe.

batch.completed — dispara uma vez, quando cada documento no lote atinge um status terminal:

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

document.bbox_completed — dispara quando um trabalho de anotação bbox acionado em qualquer documento deste lote termina:

{
  "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"
  }
}

Nenhuma das cargas úteis contém os resultados extraídos em si — chame GET /batches/{batch_name}/results ou GET /documents/{document_id}/bbox após receber o evento correspondente para buscar os dados reais. Ambos os eventos são entregues no máximo uma vez por conclusão, mesmo quando vários documentos (ou vários grupos de linhas bbox) atingem um status terminal em momentos próximos — consulte o guia de Webhooks para os cabeçalhos de assinatura e o cronograma de novas tentativas.

Listar eventos

Retorna um feed de eventos persistido, do mais recente ao mais antigo, para integrações de polling. Este é o endpoint certo para gatilhos de polling do Zapier, como "Novo Lote Concluído", "Novo Documento Concluído" e "Extração Falhou" — ele não exige que os usuários insiram manualmente um batch_name no gatilho.

GET /api/v1/events

Parâmetros

Nome	Local	Tipo	Descrição
`type`	query, opcional	string	Um de `batch.completed`, `document.completed`, `document.failed`.
`limit`	query, opcional	integer	1-100. Padrão 20.
`page_token`	query, opcional	string	Cursor opaco de um `next_page_token` de uma resposta anterior.
`batch_name`	query, opcional	string	Restringir eventos a um lote.
`document_id`	query, opcional	string	Restringir eventos a um documento.
`created_from`	query, opcional	datetime	Retornar eventos criados a partir deste timestamp ISO 8601.
`created_to`	query, opcional	datetime	Retornar eventos criados até este timestamp ISO 8601.

Os eventos são criados somente após o worker ter confirmado o estado final do documento, portanto, quando um evento aparece aqui, seus destinos document_url, batch_url e batch_results_url são seguros para leitura. Use id como chave de deduplicação. Se um documento com falha for reprocessado e atingir um estado final novamente, ou se um lote concluído receber outra onda processada posteriormente, a nova conclusão recebe um novo id de evento.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
invalid_parameter — type, limit, page_token, batch_name, created_from ou created_to inválidos.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
missing_parameter (param: "callback_url")
invalid_parameter (param: "callback_url") — não é uma URL http:///https://.
invalid_parameter (param: "batch_name")

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"}'

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())

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());

{ "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 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/events", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"type": "batch.completed", "limit": 20}, ) print(response.json())

{ "events": [ { "id": "evt_3f9c9e2a1b7d4e2b9a3e2f5b6c7d8e9f", "type": "batch.completed", "created_at": "2026-08-04T08:31:22+00:00", "batch_name": "260804-4K9P", "document_id": null, "status": "succeeded", "document_count": 3, "filename": null, "error": null, "batch_url": "https://imagetotable.ai/api/v1/batches/260804-4K9P", "batch_results_url": "https://imagetotable.ai/api/v1/batches/260804-4K9P/results" } ], "has_more": false, "next_page_token": null }