Webhook do Agentic Content Extraction

Quando o processamento termina, o Connect chama o seu servidor (servidor de callback) e envia o resultado da extração. Esta página explica como configurar o webhook na requisição, o que o seu servidor recebe e o que fazer se a entrega falhar.

INFO

Esta página vale para o fluxo AGENTIC_CONTENT_EXTRACTION, iniciado pela rota Agentic Content Extraction Async (POST /connect/async).

Como funciona

Você envia a requisição para /connect/async com o flowCode AGENTIC_CONTENT_EXTRACTION e, em parameters, o fileUrl, as tags e o objeto webhook.

O Connect responde na hora com o processId. Guarde-o: ele identifica o processo e é usado na consulta de status.

Ao fim do processamento, o Connect faz um POST para a url informada, com o resultado no corpo.

Se a chamada à url falhar, o Connect chama a fallbackUrl, se ela tiver sido informada.

O resultado fica disponível na rota Agentic Content Extraction Async Status por até 1 hora a partir da requisição inicial.

Configurar o webhook

Os campos marcados com 🔸 são obrigatórios.

{
  "flowCode": "AGENTIC_CONTENT_EXTRACTION",
  "parameters": {
    "fileUrl": "https://seuservidor.com/arquivos/invoice.pdf",
    "tags": ["id=zzz-nlp-invoice-1"],
    "webhook": {
      "url": "https://seuservidor.com/retorno",
      "fallbackUrl": "https://seuservidor.com/retorno-contingencia",
      "authorization": {
        "headers": [
          { "name": "nomeCabecalho1", "value": "valorCabecalho1" }
        ],
        "queryStrings": [
          { "name": "nomeQs1", "value": "valorQs1" }
        ]
      }
    }
  }
}

WARNING

O webhook fica dentro de parameters, junto com o fileUrl e as tags, e não no primeiro nível da requisição como nas rotas assíncronas do mostQI.

Parâmetros

parameters.webhook

Campo	Tipo	Obrigatório	Descrição
`url`	string	🔸	URL chamada quando o processamento termina. Deve aceitar requisições `POST`.
`fallbackUrl`	string		URL de contingência, chamada somente se a chamada à `url` falhar.
`authorization`	object		Cabeçalhos e query strings que o Connect repassa ao seu servidor.

parameters.webhook.authorization

Campo	Tipo	Descrição
`headers`	array	Lista de cabeçalhos HTTP (`name` e `value`) repassados à `url` e à `fallbackUrl`.
`queryStrings`	array	Lista de parâmetros de query string (`name` e `value`) adicionados à `url` e à `fallbackUrl`.

Requisitos do seu servidor

Método: o endpoint de callback deve aceitar requisições POST e processar o corpo com o resultado da extração.

Rede: não pode haver bloqueio de firewall ou regra de rede que impeça a infraestrutura da MOST de entregar os dados ao seu servidor.

Arquivo: o fileUrl deve permitir o download direto, sem autenticação ou interação humana.

O que o seu servidor recebe

O Connect faz um POST para a url configurada, com os cabeçalhos e as query strings informados em authorization. O corpo tem o mesmo formato da resposta da rota de status: o objeto result com o resultado do processo, mais requestId, elapsedMilliseconds e status.

Campo	Descrição
`result.status`	Situação do processo: `PROCESSED` (sucesso) ou `FAILED` (erro). É este campo que indica se a extração deu certo.
`result.processId`	Identificador do processo, o mesmo retornado no envio.
`result.requestId`	Identificador da requisição original de envio.
`result.createdAt` / `result.updatedAt`	Data e hora de criação e da última atualização do processo.
`result.documents`	Documentos encontrados, com `type`, `stdType` e `extractions`.
`requestId`	Identificador desta chamada.
`elapsedMilliseconds`	Tempo de processamento, em milissegundos.
`status`	Código e mensagem de status da chamada (`code`, `message`, `errors`). Vem `"200"` também quando o processo falha.

Para saber se o processamento deu certo, verifique result.status:

PROCESSED: a extração terminou e os dados estão em result.documents.

FAILED: ocorreu um erro no processamento, por exemplo arquivo corrompido ou inacessível. Nesse caso, result.documents vem null.

WARNING

O status.code do primeiro nível vem "200" também quando o processo falha: ele indica que a chamada foi entregue, não que a extração deu certo. Use sempre o result.status para saber o resultado do processamento.

Estrutura do resultado

Cada documento traz uma lista de extractions. Cada extração tem score, tags, source e sections. Cada seção tem:

fields: campos com name, stdName, value e score;

tables: tabelas com headers (colunas) e values (linhas). Cada linha é uma lista de células com name, stdName, value e score.

Os campos name vêm em português e os campos stdName, padronizados em inglês.

Exemplo: extração com sucesso

Exemplo resumido de um balanço patrimonial, com dados fictícios. A tabela traz só dois anos; o retorno completo traz todos os períodos encontrados no documento.

{
  "result": {
    "status": "PROCESSED",
    "processId": "01a15f99-5dd8-1299-89ef-9e0170d8b35f",
    "requestId": "HZyDT8T37ik5RCoM7IivP",
    "createdAt": "2026-10-21T17:54:10.227Z",
    "updatedAt": "2026-10-21T17:55:06.903Z",
    "documents": [
      {
        "type": "declaracao",
        "stdType": "statement",
        "extractions": [
          {
            "source": "iocr",
            "score": 0.99,
            "tags": ["id=bra-nlp-balanco-patrimonial-1", "country=bra", "person=legal", "type=declaracao"],
            "sections": [
              {
                "name": "secao_documento",
                "stdName": "section_document",
                "score": 0.99,
                "fields": [
                  { "name": "nome", "stdName": "name", "value": "ACME LTDA", "score": 0.99 },
                  { "name": "cnpj", "stdName": "cnpj", "value": "12345678000190", "score": 0.98 },
                  { "name": "data_emissao", "stdName": "issue_date", "value": "2017-07-04", "score": 0.99 },
                  { "name": "periodo_balanco", "stdName": "balance_sheet_period", "value": null, "score": null }
                ],
                "tables": [
                  {
                    "name": "tabela_balanco",
                    "stdName": "table_balance_sheet",
                    "score": 0.99,
                    "headers": [
                      { "name": "data", "stdName": "date", "score": 0.99 },
                      { "name": "valor_total_ativo", "stdName": "assets_total_value", "score": 0.99 },
                      { "name": "valor_total_patrimonio_liquido", "stdName": "equity_total_value", "score": 0.99 }
                    ],
                    "values": [
                      [
                        { "name": "data", "stdName": "date", "value": "2016-12-31", "score": 0.99 },
                        { "name": "valor_total_ativo", "stdName": "assets_total_value", "value": "1129244.69", "score": 0.99 },
                        { "name": "valor_total_patrimonio_liquido", "stdName": "equity_total_value", "value": "1102262.57", "score": 0.99 }
                      ],
                      [
                        { "name": "data", "stdName": "date", "value": "2015-12-31", "score": 0.99 },
                        { "name": "valor_total_ativo", "stdName": "assets_total_value", "value": "1087555.91", "score": 0.99 },
                        { "name": "valor_total_patrimonio_liquido", "stdName": "equity_total_value", "value": "1065034.69", "score": 0.99 }
                      ]
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "requestId": "HZyDT8T37ik5RCoM7IivP",
  "elapsedMilliseconds": 56675,
  "status": { "message": "Ok", "code": "200", "errors": null }
}

INFO

Campos e células não encontrados no documento vêm com value e score iguais a null.

Exemplo: processamento com falha

{
  "result": {
    "status": "FAILED",
    "processId": "01a15f93-9236-9cb4-d899-036634bca685",
    "requestId": "QAw4lw1bGiChuQ4PUiV1h",
    "createdAt": "2026-10-21T17:47:53.884Z",
    "updatedAt": "2026-10-21T17:51:32.245Z",
    "documents": null
  },
  "requestId": "QAw4lw1bGiChuQ4PUiV1h",
  "elapsedMilliseconds": 218360,
  "status": { "message": "Ok", "code": "200", "errors": null }
}

INFO

Mesmo quando o processamento falha, o webhook é enviado. A falha está no conteúdo (result.status), não na entrega.

TIP

A ordem dos atributos no JSON é dinâmica e pode mudar sem aviso. Localize seções, campos, tabelas e colunas sempre pelo name, nunca pela posição. As linhas de uma tabela também podem vir fora de ordem; no exemplo acima, use o campo data para identificar cada período.

O que o seu servidor deve responder

Responda com um código HTTP 2xx (por exemplo, 200) para confirmar o recebimento.

Responda rápido e processe o conteúdo depois, em segundo plano.

Se o webhook não chegar

Consulte a rota Agentic Content Extraction Async Status com o processId:

{
  "flowCode": "AGENTIC_CONTENT_EXTRACTION",
  "parameters": {
    "processId": "019c1f50-6246-55f2-737c-f49ce529f9dd"
  }
}

`status`	Significado
`NOT_STARTED`	O processo foi recebido e está na fila de execução.
`PROCESSING`	O agente está lendo e interpretando o documento.
`PROCESSED`	Extração finalizada com sucesso. O resultado está disponível.
`FAILED`	Ocorreu um erro durante o processamento.

WARNING

O resultado fica disponível por 1 hora a partir da requisição inicial. Depois disso, ele é removido por segurança e conformidade com a LGPD, e a rota de status retorna o erro R125.

Limites de requisição

Rota	Limite
`POST /connect/async`	2 requisições por minuto por cliente. Acima disso, as tarefas podem ir para fila ou retornar HTTP 429.
`POST /connect/async/status`	8 requisições por segundo por cliente.

Prefira o webhook e use a rota de status como contingência ou para consultas pontuais.

Boas práticas

Use https e um cabeçalho de autenticação próprio em authorization.headers para validar que a chamada veio da MOST.

Relacione pelo processId. Guarde o processId retornado no envio e use-o para associar o resultado recebido à requisição original.

Configure a fallbackUrl em outro servidor ou outra infraestrutura, para que uma indisponibilidade não afete as duas URLs.

Consulte o status dentro de 1 hora. Se o webhook não chegar, recupere o resultado antes de ele expirar.

Retorno do webhook

Webhook do Agentic Content Extraction#

Como funciona#

Configurar o webhook#

Parâmetros#

parameters.webhook#

parameters.webhook.authorization#

Requisitos do seu servidor#

O que o seu servidor recebe#

Estrutura do resultado#

Exemplo: extração com sucesso#

Exemplo: processamento com falha#

O que o seu servidor deve responder#

Se o webhook não chegar#

Limites de requisição#

Boas práticas#

Webhook do Agentic Content Extraction

Como funciona

Configurar o webhook

Parâmetros

parameters.webhook

parameters.webhook.authorization

Requisitos do seu servidor

O que o seu servidor recebe

Estrutura do resultado

Exemplo: extração com sucesso

Exemplo: processamento com falha

O que o seu servidor deve responder

Se o webhook não chegar

Limites de requisição

Boas práticas