Retorno do Webhook

Quando um webhook é informado no envio do documento, o mostValid notifica a URL configurada quando o documento é encaminhado para revisão e quando o processo atinge um status final, enviando o resultado do processamento. Dessa forma, não é necessário consultar periodicamente a rota de status para saber se o resultado está disponível.

Configurando o webhook

O webhook é configurado na própria requisição de envio do documento, tanto em application/json quanto em multipart/form-data.

Parâmetro	Obrigatório	Descrição
`webhook.url`	Não. Obrigatório quando o webhook for informado.	URL que receberá as notificações do processo.
`webhook.fallbackUrl`	Não	URL alternativa, utilizada quando não for possível entregar a notificação na `webhook.url`.

No envio em JSON, os parâmetros são informados dentro do objeto webhook:

{
  "fileUrl": "https://exemplo.com.br/documentos/boletim-ocorrencia.pdf",
  "webhook": {
    "url": "https://seu-dominio.com.br/webhook/mostvalid",
    "fallbackUrl": "https://seu-dominio.com.br/webhook/mostvalid-fallback"
  }
}

No envio em form-data, os mesmos parâmetros são informados como campos webhook.url e webhook.fallbackUrl.

Importante: as URLs informadas devem ser públicas, utilizar HTTPS e estar preparadas para receber requisições POST com corpo application/json.

Quando o webhook é enviado

`processStatus`	Quando ocorre
`TO_ANALYSIS`	O documento precisa de complementação e foi gerada uma tarefa de revisão no Portal mostValid.
`FINISHED`	O processo foi concluído e o resultado está disponível, com ou sem revisão.
`ERROR`	Ocorreu um erro no processamento. O motivo é informado em `processStatusDescription`.

Os status IN_PROCESS, IN_ANALYSIS e CANCELED não geram notificação via webhook.

Atenção: um mesmo processo pode gerar mais de uma notificação. Quando o documento vai para revisão, sua aplicação recebe primeiro um webhook com TO_ANALYSIS e, após a conclusão da revisão, um segundo webhook com FINISHED. Utilize o campo processStatus para identificar a etapa de cada notificação.

Estrutura do payload

O corpo enviado ao webhook segue a mesma estrutura da resposta da rota de status, com uma diferença: os metadados da requisição HTTP (requestId, elapsedMilliseconds e status) não são enviados, pois o webhook não é a resposta a uma chamada feita pelo cliente.

Campo	Tipo	Descrição
`mostQiRequestId`	string	Identificador da requisição de extração.
`processId`	string (UUID)	Identificador do processo, o mesmo retornado no envio do documento. Utilize-o para relacionar o webhook à requisição original.
`processStatus`	string	Status do processo no momento da notificação: `TO_ANALYSIS`, `FINISHED` ou `ERROR`.
`processStatusDescription`	string \| null	Detalhe sobre o status do processo. É preenchido principalmente em casos de `ERROR`, com o motivo da falha; nos demais casos, geralmente é enviado como `null`.
`result`	array \| null	Resultado da extração, organizado em `extractions`, `sections`, `fields` e `tables`. Em casos de `ERROR`, é enviado como `null`.

Status dos itens no resultado

Cada extração, seção, campo, cabeçalho e célula de tabela possui um status que indica se o item passou por revisão e qual foi o resultado:

Status	Descrição
`MOSTQIIOCR`	O item não foi enviado para revisão, pois a extração automática já atende às regras definidas pelo cliente.
`TO_ANALYSIS`	O item necessita de revisão e está aguardando análise. Aparece apenas no webhook de `TO_ANALYSIS`.
`REVIEWED`	O item foi revisado e o conteúdo original foi confirmado, sem alteração.
`MODIFIED`	O item sofreu alguma alteração durante a revisão. Em campos e células, indica que o valor original foi alterado pelo revisor. Em extrações e seções, indica que houve alteração em itens contidos nelas durante a revisão.
`UNREADABLE`	O item foi revisado e marcado como ilegível. Nesse caso, o `finalValue` é enviado como `null`, mesmo que o `value` esteja preenchido.

Use sempre o finalValue. O campo value contém o valor extraído automaticamente; o finalValue contém o valor final, já considerando a revisão. Um campo REVIEWED com finalValue igual a null, por exemplo, indica que o revisor confirmou que a informação não consta no documento.

Exemplos de payload

Processo finalizado (FINISHED)

Exemplo de webhook de um boletim de ocorrência de duas páginas, finalizado após revisão. Observe que:

os campos endereco e natureza_ocorrencia não precisaram de revisão (MOSTQIIOCR);

os campos data, hora e tipo_local não foram encontrados na extração automática e foram enviados para revisão; o revisor confirmou que a informação não consta no documento, e eles retornam como REVIEWED, com finalValue igual a null;

a seção e a extração retornam como REVIEWED, pois houve revisão, mas nenhum valor foi alterado.

{
  "mostQiRequestId": "Mp4qRs7TuV0wXy3ZaB6cD",
  "processId": "2d8f4b6a-9c1e-4a3f-b5d7-8e0a2c4f6b9d",
  "processStatus": "FINISHED",
  "processStatusDescription": null,
  "result": [
    {
      "type": "certificado",
      "stdType": "certificate",
      "extractions": [
        {
          "source": "iocr",
          "score": 0.35,
          "status": "REVIEWED",
          "tags": [
            "country=bra",
            "goal=attest",
            "has=address",
            "id=bra-boletim-ocorrencia-21",
            "language=pt-BR",
            "of=document",
            "std-type=certificate",
            "subtype=boletim-ocorrencia",
            "subtype=police-report",
            "type=certificado"
          ],
          "sections": [
            {
              "name": "secao_infracao_penal",
              "stdName": null,
              "score": 0.35,
              "status": "REVIEWED",
              "fields": [
                {
                  "name": "endereco",
                  "stdName": null,
                  "value": "do Fato: AVENIDA EXEMPLO, 1000 - JARDIM FICTÍCIO - 5° ANDAR - 01234 - 567 - SÃO PAULO - SP",
                  "finalValue": "do Fato: AVENIDA EXEMPLO, 1000 - JARDIM FICTÍCIO - 5° ANDAR - 01234 - 567 - SÃO PAULO - SP",
                  "score": 0.89,
                  "status": "MOSTQIIOCR"
                },
                {
                  "name": "natureza_ocorrencia",
                  "stdName": null,
                  "value": "Data do 10/03/2025 Hora Aproximada: 14: 00 às 14: 59 Declarante Nome: MARIA SILVA SANTOS Sexo: FEMININO Naturalidade: CAMPINAS - SP Nascimento: 20/04/1995 Nome da Mãe: ANA SILVA SANTOS Nome do Pai: CARLOS SANTOS OLIVEIRA Documentos CPF: 123.456.789 - 09 Tipo de Registro: R. G. UF RG: SP Número do Registro: 12345678 - 9 Profissão e Informações de Contato Profissão: ANALISTA E - mail: MARIA. SANTOS@EXEMPLO. COM. BR Telefone: (11) 3000 - 0000 Tipo: COMERCIAL Ramal/Pessoa de Contato: MARIA SANTOS Telefone: (11) 91234 - 5678 Tipo: CONTATO Ramal/Pessoa de Contato: MARIA SANTOS Endereço Residencial RUA DAS ACÁCIAS, 100 - VILA FICTÍCIA - CASA 2 - 02345 - 678 - SÃO PAULO - SP Endereço Comercial AVENIDA EXEMPLO, 1000 - JARDIM FICTÍCIO - 5° ANDAR - 01234 - 567 - SÃO PAULO - SP Documentos Pessoais Proprietário do Documento: MARIA SILVA SANTOS Documento: VALE REFEIÇÃO Número do Registro: 12345678 - 9 CPF: 123.456.789 - 09 Data de Nascimento: 20/04/1995 Nome da Mãe: ANA SILVA SANTOS Nome do Pai: CARLOS SANTOS OLIVEIRA Telefone: (11) 91234 - 5678 Vale Refeição Bandeira: BANDEIRA EXEMPLO Empresa do Registro: DATADO 05/03/2025 - Detalhe da Ocorrência 1/2 Perda - B. E. O.: - 0000123456/2025 EU MARIA SILVA SANTOS DECLARO, SOB AS PENAS DA LEI, QUE EXTRAVIEI OS ITENS ELENCADOS Informações Adicionais Data da Comunicação: 11/03/2025 ÀS 09: 15 Data de Atendimento: 11/03/2025 às 09: 20 Delegacia Circunscricional: 99º D. P. EXEMPLO Detalhes do Atendimento: A REDAÇÃO DO PRESENTE BOLETIM ELETRÔNICO DE OCORRÊNCIA FOI ELABORADA PELO DECLARANTE E AS INFORMAÇÕES NELE CONSTANTES SÃO DE SUA EXCLUSIVA RESPONSABILIDADE. ESTE B. E. O. NÃO SUBSTITUI OS DOCUMENTOS ORIGINAIS. IMPORTANTE: - MESMO QUE OS DOCUMENTOS SEJAM RECUPERADOS, NÃO HAVERÁ POSSIBILIDADE DE CANCELAMENTO DESTE B. E. O.. Paulo Roberto Exemplo Delegado de Polícia 0000123456/2025 Imprima quantas cópias precisar deste boletim Obrigado por usar os serviços da Delegacia Eletrônica 2/2",
                  "finalValue": "Data do 10/03/2025 Hora Aproximada: 14: 00 às 14: 59 Declarante Nome: MARIA SILVA SANTOS Sexo: FEMININO Naturalidade: CAMPINAS - SP Nascimento: 20/04/1995 Nome da Mãe: ANA SILVA SANTOS Nome do Pai: CARLOS SANTOS OLIVEIRA Documentos CPF: 123.456.789 - 09 Tipo de Registro: R. G. UF RG: SP Número do Registro: 12345678 - 9 Profissão e Informações de Contato Profissão: ANALISTA E - mail: MARIA. SANTOS@EXEMPLO. COM. BR Telefone: (11) 3000 - 0000 Tipo: COMERCIAL Ramal/Pessoa de Contato: MARIA SANTOS Telefone: (11) 91234 - 5678 Tipo: CONTATO Ramal/Pessoa de Contato: MARIA SANTOS Endereço Residencial RUA DAS ACÁCIAS, 100 - VILA FICTÍCIA - CASA 2 - 02345 - 678 - SÃO PAULO - SP Endereço Comercial AVENIDA EXEMPLO, 1000 - JARDIM FICTÍCIO - 5° ANDAR - 01234 - 567 - SÃO PAULO - SP Documentos Pessoais Proprietário do Documento: MARIA SILVA SANTOS Documento: VALE REFEIÇÃO Número do Registro: 12345678 - 9 CPF: 123.456.789 - 09 Data de Nascimento: 20/04/1995 Nome da Mãe: ANA SILVA SANTOS Nome do Pai: CARLOS SANTOS OLIVEIRA Telefone: (11) 91234 - 5678 Vale Refeição Bandeira: BANDEIRA EXEMPLO Empresa do Registro: DATADO 05/03/2025 - Detalhe da Ocorrência 1/2 Perda - B. E. O.: - 0000123456/2025 EU MARIA SILVA SANTOS DECLARO, SOB AS PENAS DA LEI, QUE EXTRAVIEI OS ITENS ELENCADOS Informações Adicionais Data da Comunicação: 11/03/2025 ÀS 09: 15 Data de Atendimento: 11/03/2025 às 09: 20 Delegacia Circunscricional: 99º D. P. EXEMPLO Detalhes do Atendimento: A REDAÇÃO DO PRESENTE BOLETIM ELETRÔNICO DE OCORRÊNCIA FOI ELABORADA PELO DECLARANTE E AS INFORMAÇÕES NELE CONSTANTES SÃO DE SUA EXCLUSIVA RESPONSABILIDADE. ESTE B. E. O. NÃO SUBSTITUI OS DOCUMENTOS ORIGINAIS. IMPORTANTE: - MESMO QUE OS DOCUMENTOS SEJAM RECUPERADOS, NÃO HAVERÁ POSSIBILIDADE DE CANCELAMENTO DESTE B. E. O.. Paulo Roberto Exemplo Delegado de Polícia 0000123456/2025 Imprima quantas cópias precisar deste boletim Obrigado por usar os serviços da Delegacia Eletrônica 2/2",
                  "score": 0.86,
                  "status": "MOSTQIIOCR"
                },
                {
                  "name": "data",
                  "stdName": null,
                  "value": null,
                  "finalValue": null,
                  "score": null,
                  "status": "REVIEWED"
                },
                {
                  "name": "hora",
                  "stdName": null,
                  "value": null,
                  "finalValue": null,
                  "score": null,
                  "status": "REVIEWED"
                },
                {
                  "name": "tipo_local",
                  "stdName": null,
                  "value": null,
                  "finalValue": null,
                  "score": null,
                  "status": "REVIEWED"
                }
              ],
              "tables": []
            }
          ]
        }
      ]
    }
  ]
}

Processo com erro (ERROR)

Exemplo de webhook de um processo que não pôde ser processado porque o arquivo enviado está protegido por senha. Neste caso, o result é null e o motivo do erro é informado em processStatusDescription.

{
  "mostQiRequestId": "Lm4nPq7RsT1uVw3XyZ5Ab",
  "processId": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "processStatus": "ERROR",
  "processStatusDescription": "The uploaded file is encrypted by a password",
  "result": null
}

Processo enviado para revisão (TO_ANALYSIS)

O webhook de TO_ANALYSIS segue a mesma estrutura do exemplo de FINISHED. O result traz os dados extraídos até o momento, e os itens que aguardam revisão aparecem com status TO_ANALYSIS. Esse webhook serve para informar que o documento está em revisão; o resultado definitivo deve ser considerado apenas no webhook de FINISHED.

Boas práticas para receber o webhook

Responda rapidamente. Retorne um status HTTP 2xx assim que receber a requisição e processe o conteúdo de forma assíncrona, evitando que a entrega seja considerada como falha.

Use o processId como chave. Relacione o webhook ao documento enviado por meio do processId. Como um mesmo processo pode notificar TO_ANALYSIS e depois FINISHED, use o processStatus para decidir a ação e trate de forma idempotente uma mesma notificação recebida mais de uma vez.

Considere o status de cada item. Antes de usar um valor, verifique o status do item: valores UNREADABLE têm finalValue nulo e podem exigir tratamento específico na sua aplicação, como solicitar um novo documento.

Trate os erros. Em um webhook com ERROR, verifique o processStatusDescription para identificar o motivo, como um arquivo protegido por senha, e, se for o caso, reenvie o documento corrigido (por exemplo, informando o filePassword).

Tenha uma alternativa. Caso sua aplicação não receba o webhook, o resultado pode ser consultado na rota de status, informando o processId, por até uma hora após o processo atingir um status final.

Retorno do Webhook

Configurando o webhook#

Quando o webhook é enviado#

Estrutura do payload#

Status dos itens no resultado#

Exemplos de payload#

Processo finalizado (FINISHED)#

Processo com erro (ERROR)#

Processo enviado para revisão (TO_ANALYSIS)#

Boas práticas para receber o webhook#