Retorno do webhook

Quando uma consulta assíncrona 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 corpo enviado ao seu servidor traz o processId e o mesmo objeto result retornado pela rota Enrichment Async Status.

Como funciona

Você envia a consulta para a rota Enrichment Async com o objeto webhook.

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

Quando a consulta de todos os datasets termina, 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 fica disponível na rota de status. [validar: prazo de retenção do resultado]

Configurar o webhook

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

{
  "query": "pf",
  "parameters": {
    "cpf": "00000000000"
  },
  "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" }
      ]
    }
  }
}

Parâmetros

webhook

Campo	Tipo	Obrigatório	Descrição
`url`	string	🔸	URL chamada quando a consulta assíncrona 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: [validar: mesmas regras do Content Extraction]

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. [validar: disponível no Enrichment]

webhook.authorization.headers[]

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

Regras: [validar: mesmas regras do Content Extraction]

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.

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 processId e o objeto result com o resultado da consulta.

Como saber se a consulta deu certo

No Enrichment, o resultado é avaliado em dois níveis:

Nível	Campo	Valores
Consulta	`result.status`	`DONE`: todos os datasets terminaram, com ou sem sucesso. `ERROR`: todos os datasets retornaram erro.
Dataset	`result.datasets[].status`	`DONE`: os dados estão em `data`. `ERROR`: `data` vem `null` e o motivo está em `errors`.

WARNING

result.status igual a DONE não garante que todos os datasets tiveram sucesso. Verifique sempre o status de cada item de datasets.

Exemplo: consulta com sucesso

Exemplo resumido de uma consulta de situação cadastral do CPF; a lista fields completa traz todos os campos retornados pela fonte.

{
  "processId": "20b951c1-daa6-48af-9c4f-963200b75cac",
  "result": {
    "query": "PF_01",
    "status": "DONE",
    "parameters": {
      "cpf": "00000000000",
      "data_nascimento": "1951-10-12"
    },
    "datasets": [
      {
        "name": "rf_situacao_cadastral_cpf",
        "code": "rf_situacao_cadastral_cpf_ondemand_817669",
        "status": "DONE",
        "errors": [],
        "data": [
          {
            "id": "bra-situacao-cadastral-cpf-1",
            "type": "documento-pessoal",
            "tags": ["country=bra", "goal=query", "id=bra-situacao-cadastral-cpf-1", "person=natural"],
            "fields": [
              { "name": "cpf", "origin_name": "No do CPF", "score": null, "value": "00000000000" },
              { "name": "nome", "origin_name": "Nome", "score": null, "value": "MARIA DA SILVA" },
              { "name": "situacao", "origin_name": "Situação Cadastral", "score": null, "value": "REGULAR" },
              { "name": "codigo_autenticacao", "origin_name": null, "score": null, "value": "XXXX.XXXX.XXXX.XXXX" }
            ],
            "tables": []
          }
        ]
      }
    ]
  }
}

Exemplo: consulta com erro no dataset

{
  "processId": "20b951c1-daa6-48af-9c4f-963200b75cac",
  "result": {
    "query": "PF_01",
    "status": "ERROR",
    "parameters": {
      "cpf": "00000000000",
      "data_nascimento": "1951-10-11"
    },
    "datasets": [
      {
        "name": "rf_situacao_cadastral_cpf",
        "code": "rf_situacao_cadastral_cpf_ondemand_817669",
        "status": "ERROR",
        "errors": [
          "SOURCE MESSAGE: Data de nascimento está divergente da constante na base de dados da Secretaria da Receita Federal do Brasil"
        ],
        "data": null
      }
    ]
  }
}

INFO

Mesmo quando a consulta falha, o webhook é enviado. A falha está no conteúdo (status da consulta e dos datasets), 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. [validar]

O mostQI faz 1 tentativa em cada URL: uma na url e, se ela falhar, uma na fallbackUrl. [validar]

Responda rápido e processe o conteúdo depois, em segundo plano. [validar: tempo máximo de espera pela resposta]

TIP

Se as duas URLs falharem, o resultado não se perde: consulte a rota Enrichment Async Status com o processId.

Acompanhar a consulta pela rota de status

A rota de status retorna a situação da consulta (TODO, DOING, DONE ou ERROR) e os dados já obtidos de cada dataset. Use-a quando o webhook não chegar ou para acompanhar consultas longas.

Status	Consulta (`result.status`)	Dataset (`datasets[].status`)
`TODO`	Consulta não iniciada.	Consulta não iniciada.
`DOING`	Consulta em execução.	Consulta em execução.
`DONE`	Todos os datasets terminaram, com ou sem sucesso.	Consulta finalizada.
`ERROR`	Todos os datasets retornaram erro.	Erro no dataset ou indisponibilidade da fonte de dados.

Quando o processo não é mais encontrado, a rota de status retorna o erro R125.

[validar: se a rota de status do Enrichment também traz o objeto webhookStatus, com a situação de cada tentativa de entrega, como no Content Extraction. Se trouxer, incluir aqui a mesma seção da página de webhook do Content Extraction.]

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.

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

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

Verifique cada dataset. Uma consulta DONE pode ter datasets com ERROR, por exemplo por indisponibilidade da fonte.

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.

Erros de configuração

Código	Descrição
R138	Invalid webhook configuration [validar: retornado também no Enrichment]

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

Como funciona#

Configurar o webhook#

Parâmetros#

webhook#

webhook.authorization#

webhook.authorization.headers[]#

webhook.authorization.queryStrings[]#

O que o seu servidor recebe#

Como saber se a consulta deu certo#

Exemplo: consulta com sucesso#

Exemplo: consulta com erro no dataset#

O que o seu servidor deve responder#

Acompanhar a consulta pela rota de status#

Boas práticas#

Erros de configuração#

Como funciona

Configurar o webhook

Parâmetros

webhook

webhook.authorization

webhook.authorization.headers[]

webhook.authorization.queryStrings[]

O que o seu servidor recebe

Como saber se a consulta deu certo

Exemplo: consulta com sucesso

Exemplo: consulta com erro no dataset

O que o seu servidor deve responder

Acompanhar a consulta pela rota de status

Boas práticas

Erros de configuração