Webhooks

Registre uma URL para ser chamada quando o processamento de um lote for concluído, em vez de consultar o status do lote. Esta página cobre o único endpoint de registro; para a estrutura do payload, os três cabeçalhos de assinatura e a programação de novas tentativas, consulte o Guia de Webhooks — incluindo como o reprocessamento de 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 conclusão de bbox. A mesma callback_url que você registra aqui também recebe um evento document.bbox_completed sempre que um trabalho de anotação bbox for concluído em qualquer documento deste lote — acionar bbox não requer (nem suporta) seu próprio endpoint de webhook. Consulte o Guia de Webhooks para a estrutura do payload do evento e a ressalva de entrega específica para 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 webhook separadamente, por exemplo, antes de estar pronto para chamar process, ou para corrigir uma URL digitada errado posteriormente.

Parâmetros

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, portanto, reenviar um PUT com o mesmo callback_url é a forma suportada de recuperar seu segredo novamente se você o perder. Atualizar um registro existente afeta apenas 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 garante que você seja notificado novamente.

Cargas de eventos entregues

Após o registro, o callback_url recebe um POST para um dos dois tipos de evento, diferenciados pelo campo "type" de nível superior — este endpoint nunca retorna nenhuma das formas; estas 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 é concluído:

{
  "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 carga 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 cronograma de repetição.

Erros possíveis

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