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	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/commercial-invoice.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 item marcado como UNREADABLE, por exemplo, mantém o value original, mas não deve ser utilizado, pois o finalValue é null.

Exemplos de payload

Processo finalizado (FINISHED)

Exemplo de webhook de uma commercial invoice finalizada após revisão. Observe que:

os campos da seção section_header foram marcados como ilegíveis pelo revisor (UNREADABLE) e retornam com finalValue igual a null, embora o value original esteja preenchido;

os campos de identificação da seção section_supplier e os campos sem valor nas tabelas foram confirmados pelo revisor (REVIEWED);

os demais itens não precisaram de revisão (MOSTQIIOCR).

a extração retorna com status MODIFIED, pois houve alteração em itens durante a revisão.

{
    "mostQiRequestId": "Ac3dEf6GhI9jKl2MnO5pQ",
    "processId": "4f7a2c9e-1b3d-4e6f-8a0b-2c4d6e8f0a1b",
    "processStatus": "FINISHED",
    "processStatusDescription": null,
    "result": [
        {
            "type": "fiscal-document",
            "stdType": "fiscal-document",
            "extractions": [
                {
                    "source": "iocr",
                    "score": 0.9,
                    "status": "MODIFIED",
                    "tags": [
                        "id=zzz-nlp-invoice-1",
                        "language=en-US",
                        "goal=charge",
                        "subtype=invoice",
                        "std-type=fiscal-document",
                        "type=fiscal-document"
                    ],
                    "sections": [
                        {
                            "name": "section_header",
                            "stdName": "section_header",
                            "score": 0.98,
                            "status": "UNREADABLE",
                            "fields": [
                                {
                                    "name": "invoice_number",
                                    "stdName": "invoice_number",
                                    "value": "INV20250901",
                                    "finalValue": null,
                                    "score": 0.99,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "issue_date",
                                    "stdName": "issue_date",
                                    "value": "2025-09-02",
                                    "finalValue": null,
                                    "score": 0.91,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "currency",
                                    "stdName": "currency",
                                    "value": "USD",
                                    "finalValue": null,
                                    "score": 0.99,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "po_number",
                                    "stdName": "po_number",
                                    "value": null,
                                    "finalValue": null,
                                    "score": null,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "contract_number",
                                    "stdName": "contract_number",
                                    "value": null,
                                    "finalValue": null,
                                    "score": null,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "lc_number",
                                    "stdName": "lc_number",
                                    "value": null,
                                    "finalValue": null,
                                    "score": null,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "client_code",
                                    "stdName": "client_code",
                                    "value": null,
                                    "finalValue": null,
                                    "score": null,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "delivery_address",
                                    "stdName": "delivery_address",
                                    "value": "BAIRRO EXEMPLO, CIDADE FICTÍCIA/SC.",
                                    "finalValue": null,
                                    "score": 0.99,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "incoterms",
                                    "stdName": "incoterms",
                                    "value": null,
                                    "finalValue": null,
                                    "score": null,
                                    "status": "UNREADABLE"
                                },
                                {
                                    "name": "payment_terms",
                                    "stdName": "payment_terms",
                                    "value": nu

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#