Webhook do Content Classification Async

Quando um processo assíncrono termina, o mostQI chama o seu servidor (servidor de callback) e envia o resultado. Esta página explica como configurar o webhook na requisição, o que o seu servidor recebe e como acompanhar a entrega.

INFO

O conteúdo enviado ao seu servidor é o mesmo resultado da rota síncrona Content Classification, com o acréscimo do processId.

Como funciona

Você envia o documento para a rota assíncrona com o objeto webhook.

O mostQI responde na hora com o processId e a resultKey. Guarde os dois: eles identificam o processo e são usados na consulta de status.

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

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

O resultado e a situação da entrega ficam disponíveis na rota de status por até 1 dia.

Configurar o webhook

application/json

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

{
  "webhook": {
    "url": "https://seuservidor.com/retorno",
    "fallbackUrl": "https://seuservidor.com/retorno-contingencia",
    "authorization": {
      "headers": [
        { "name": "nomeCabecalho1", "value": "valorCabecalho1" },
        { "name": "nomeCabecalho2", "value": "valorCabecalho2" }
      ],
      "queryStrings": [
        { "name": "nomeQs1", "value": "valorQs1" },
        { "name": "nomeQs2", "value": "valorQs2" }
      ],
      "mtls": false
    }
  }
}

multipart/form-data

No envio via multipart/form-data, o webhook é informado em campos planos. O índice [N] começa em 0 e define a ordem dos itens.

Campo	Exemplo
`webhookUrl` 🔸	`https://seuservidor.com/retorno`
`webhookFallbackUrl`	`https://seuservidor.com/retorno-contingencia`
`webhookAuthorizationMtls`	`false`
`webhookAuthorizationHeaders[0].name`	`nomeCabecalho1`
`webhookAuthorizationHeaders[0].value`	`valorCabecalho1`
`webhookAuthorizationQueryStrings[0].name`	`nomeQs1`
`webhookAuthorizationQueryStrings[0].value`	`valorQs1`

WARNING

No multipart/form-data, um valor não reconhecido em webhookAuthorizationMtls é tratado como false.

Parâmetros

webhook

Campo	Tipo	Obrigatório	Descrição
`url`	string	🔸	URL chamada quando o processo assíncrono termina.
`fallbackUrl`	string		URL de contingência, chamada somente se a chamada à `url` falhar.
`authorization`	object		Configurações de autenticação da chamada ao seu servidor.

Regras para url e fallbackUrl:

A URL deve ser absoluta, com esquema e host. Exemplo: https://seuservidor.com/retorno.

Somente os esquemas http e https são aceitos. Recomendamos https.

A URL pode ter query string própria. Ela é mantida no envio.

Se fallbackUrl for vazio ou null, o campo é ignorado.

webhook.authorization

Campo	Tipo	Padrão	Descrição
`headers`	array	`[]`	Cabeçalhos HTTP que o mostQI repassa ao seu servidor.
`queryStrings`	array	`[]`	Parâmetros de query string que o mostQI adiciona à `url` e à `fallbackUrl`.
`mtls`	boolean	`false`	Ativa a autenticação mútua por certificado (mTLS) na chamada ao seu servidor.

webhook.authorization.headers[]

Campo	Tipo	Obrigatório	Descrição
`name`	string	🔸	Nome do cabeçalho.
`value`	string		Valor do cabeçalho.

Regras:

name aceita somente letras, números e os caracteres ! # $ % & ' * + - . ^ _ ` | ~. Espaços não são permitidos.

value aceita somente caracteres imprimíveis e tabulação. Quebras de linha não são permitidas.

Itens com name e value vazios são ignorados.

Os cabeçalhos abaixo são controlados pelo mostQI e não podem ser informados. A comparação não diferencia maiúsculas de minúsculas:

accept, accept-encoding, cache-control, connection, content-disposition, content-encoding, content-length, content-type, host, keep-alive, origin, pragma, referer, transfer-encoding, upgrade

webhook.authorization.queryStrings[]

Campo	Tipo	Obrigatório	Descrição
`name`	string	🔸	Nome do parâmetro.
`value`	string		Valor do parâmetro.

Regras:

name não pode ser vazio.

Itens com name e value vazios são ignorados.

Os parâmetros informados aqui são somados aos que já existem na query string da url e da fallbackUrl.

webhook.authorization.mtls

Aceita true ou false. Também aceita os textos "true", "false", "1" e "0".

Para usar true, o mTLS precisa estar habilitado na sua conta. Se não estiver, a requisição é recusada. Fale com o suporte mostQI para habilitar.

O que o seu servidor recebe

O mostQI faz um POST para a url configurada, com:

os cabeçalhos informados em authorization.headers, além dos cabeçalhos controlados pelo mostQI;

os parâmetros de authorization.queryStrings somados à query string da URL;

no corpo, o mesmo resultado da rota síncrona, com o campo processId acrescentado.

Para saber se o processamento deu certo, verifique o status.code do corpo:

"200": o documento foi classificado e o resultado está em result.

Outro código: o processamento falhou, result vem null e status.message explica o motivo. Os códigos possíveis estão em Mensagens de Erro.

Exemplo: processamento com sucesso

Exemplo de um arquivo com um RG classificado. Cada item de result corresponde a um documento encontrado no arquivo, e classifications traz o score, as tags e as páginas em que ele aparece.

{
  "result": [
    {
      "type": "documento-pessoal",
      "stdType": "personal-document",
      "classifications": [
        {
          "source": "[validar]",
          "score": 0.98,
          "tags": ["country=bra", "id=bra-rg-marinha-2", "region=verso", "subtype=rg", "type=documento-pessoal"],
          "pages": [{ "number": 1 }],
          "image": null
        }
      ]
    }
  ],
  "requestId": "MGxcxSi5m5xVzds8oTT5Y",
  "elapsedMilliseconds": 1150,
  "status": { "message": "Ok", "code": "200", "errors": [] },
  "processId": "fe57d87e-742e-4c40-a2f8-cc8fefe1a59e"
}

TIP

O campo image só vem preenchido quando a requisição é enviada com returnImage = true. Nesse caso, ele traz a imagem do documento com a perspectiva corrigida, em base64.

Exemplo: processamento com falha

{
  "result": null,
  "requestId": "Ccs4oEhgRG1C7OYZE8tr2",
  "elapsedMilliseconds": 725,
  "status": { "message": "Unsupported file format", "code": "R130", "errors": [] },
  "processId": "c676ffce-6bd3-4eb8-824c-730ba4c8324e"
}

INFO

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

O que o seu servidor deve responder

Responda com um código HTTP 2xx (por exemplo, 200) para confirmar o recebimento. Respostas fora da faixa 2xx são registradas como falha de entrega (HTTP_ERROR).

O mostQI faz 1 tentativa em cada URL: uma na url e, se ela falhar, uma na fallbackUrl. Não há novas tentativas depois disso.

Responda rápido e processe o conteúdo depois, em segundo plano. Se o seu servidor demorar, a entrega é registrada como TIMEOUT. [validar: tempo máximo de espera pela resposta]

TIP

Se as duas URLs falharem, o resultado não se perde: consulte a rota de status com o processId enquanto o processo não expirar (até 1 dia).

Acompanhar a entrega pela rota de status

A rota Content Classification Async Status mostra a situação do processo e de cada tentativa de entrega no objeto webhookStatus.

Exemplo: a chamada à url falhou com HTTP 400 e a entrega foi feita pela fallbackUrl.

{
  "result": {
    "createdAt": "2026-10-15T10:53:47.870576+00:00",
    "updatedAt": "2026-10-15T10:53:50.425123+00:00",
    "expiresAt": "2026-10-16T10:53:50.425123+00:00",
    "processId": "fe57d87e-742e-4c40-a2f8-cc8fefe1a59e",
    "requestId": "MGxcxSi5m5xVzds8oTT5Y",
    "status": "PROCESSED",
    "output": null,
    "webhookStatus": {
      "status": "SENT",
      "webhookUrl": {
        "status": "HTTP_ERROR",
        "response": { "httpStatus": 400, "elapsedMilliseconds": 325 },
        "elapsedMilliseconds": 327,
        "tries": 1
      },
      "fallbackUrl": {
        "status": "SENT",
        "response": { "httpStatus": 200, "elapsedMilliseconds": 490 },
        "elapsedMilliseconds": 491,
        "tries": 1
      },
      "elapsedMilliseconds": 819
    }
  },
  "requestId": "HPpjFt3sEaLLsq65VWd7w",
  "elapsedMilliseconds": 115,
  "status": { "message": "Ok", "code": "200", "errors": [] }
}

webhookStatus

Campo	Tipo	Descrição
`status`	string	Situação geral da entrega. Valores na tabela abaixo.
`webhookUrl`	object	Resultado do envio para a `url` principal.
`fallbackUrl`	object	Resultado do envio para a `fallbackUrl`. Mesma estrutura de `webhookUrl`.
`elapsedMilliseconds`	integer	Tempo total gasto em todos os envios, em milissegundos.

`webhookStatus.status`	Significado
`PENDING`	O processamento terminou e o webhook ainda vai ser enviado.
`SENT`	O webhook foi entregue, pela `url` ou pela `fallbackUrl`.
`FAILED`	O webhook não foi entregue em nenhuma das URLs.

webhookUrl e fallbackUrl

Campo	Tipo	Descrição
`status`	string	Resultado do envio para aquela URL. Valores na tabela abaixo.
`response.httpStatus`	integer	Código HTTP que o seu servidor respondeu. Em caso de várias tentativas, vale a última.
`response.elapsedMilliseconds`	integer	Duração da última requisição enviada, em milissegundos.
`elapsedMilliseconds`	integer	Tempo total de todas as tentativas para aquela URL, em milissegundos.
`tries`	integer	Número de tentativas feitas para aquela URL (atualmente, 1).

`status` da URL	Significado	O que verificar
`SENT`	Entregue com sucesso.	—
`HTTP_ERROR`	O seu servidor respondeu com um código fora da faixa 2xx.	Logs do seu servidor e o `response.httpStatus`.
`TIMEOUT`	O seu servidor não respondeu a tempo.	Responda antes de processar o conteúdo.
`CONNECTION_ERROR`	Não foi possível conectar: erro de DNS, conexão interrompida, entre outros.	Endereço da URL, DNS, firewall e certificado.
`AUTH_ERROR`	Falha na autenticação da requisição de envio do webhook.	Configuração de mTLS e de autenticação.
`FAILED`	Erro interno no envio.	Fale com o suporte informando o `processId`.

Depois do expiresAt, o processo não é mais encontrado na rota de status (erro R125).

Boas práticas

Use https e um cabeçalho de autenticação próprio em authorization.headers para validar que a chamada veio do mostQI. Para mais segurança, ative o mTLS.

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

Trate recebimentos repetidos. Se o mesmo processId chegar mais de uma vez, processe o resultado só uma vez.

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

Tenha um plano B. Se o webhook não chegar, consulte a rota de status antes do expiresAt.

Erros de configuração

Código	Descrição
R138	Invalid webhook configuration

O erro R138 é retornado quando alguma regra acima não é atendida. O campo details indica qual campo está incorreto:

{
  "details": [
    {
      "field": "webhook.authorization.headers[0].name",
      "message": "Forbidden webhook header name 'Content-Type'"
    }
  ]
}

Mensagem	Causa
`Invalid webhook URL: '<url>'`	`url` ou `fallbackUrl` fora das regras.
`Invalid webhook header name '<name>'`	Nome de cabeçalho com caracteres não permitidos.
`Forbidden webhook header name '<name>'`	Cabeçalho que o mostQI não permite informar.
`Invalid webhook header value '<value>' for header '<name>'`	Valor de cabeçalho com caracteres não permitidos.
`Invalid webhook query string name '<name>'`	Nome de query string vazio.

Retorno do webhook

Webhook do Content Classification Async#

Como funciona#

Configurar o webhook#

application/json#

multipart/form-data#

Parâmetros#

webhook#

webhook.authorization#

webhook.authorization.headers[]#

webhook.authorization.queryStrings[]#

webhook.authorization.mtls#

O que o seu servidor recebe#

Exemplo: processamento com sucesso#

Exemplo: processamento com falha#

O que o seu servidor deve responder#

Acompanhar a entrega pela rota de status#

webhookStatus#

webhookUrl e fallbackUrl#

Boas práticas#

Erros de configuração#

Webhook do Content Classification Async

Como funciona

Configurar o webhook

application/json

multipart/form-data

Parâmetros

webhook

webhook.authorization

webhook.authorization.headers[]

webhook.authorization.queryStrings[]

webhook.authorization.mtls

O que o seu servidor recebe

Exemplo: processamento com sucesso

Exemplo: processamento com falha

O que o seu servidor deve responder

Acompanhar a entrega pela rota de status

webhookStatus

webhookUrl e fallbackUrl

Boas práticas

Erros de configuração