Skip to main content
O escopo search envia eventos relacionados a consultas síncronas, consultas assíncronas e histórico técnico. Use este webhook para atualizar seu sistema quando uma consulta for criada, iniciar processamento, finalizar ou falhar.

Visão geral de webhooks

Consulte o contrato base, headers, assinatura e recomendações gerais de entrega.

​
Eventos disponíveis

EventoQuando é enviado
search.queuedConsulta assíncrona criada e aguardando processamento.
search.processingConsulta assíncrona começou a ser processada.
search.completedConsulta síncrona ou assíncrona finalizada.
search.failedConsulta finalizada com falha geral.
Quando a consulta termina como completed_with_errors, o evento enviado também é search.completed. A diferença aparece em data.status.

​
Fluxo de envio

Consultas síncronas normalmente geram apenas um evento final: 
search.completed
Consultas assíncronas podem gerar mais de um evento: 
search.queued -> search.processing -> search.completed
Em caso de falha geral: 
search.queued -> search.processing -> search.failed

​
Payload base

Exemplo de consulta concluída: 
{
  "id": "evt_6eb3d0a8-9e75-4a3f-9b6e-8d7fb86df01a",
  "event": "search.completed",
  "scope": "search",
  "created_at": "2026-06-23T12:00:00Z",
  "data": {
    "search_id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "target": "person",
    "status": "completed",
    "query": {
      "taxid": "00000000000",
      "datasets": ["person_basic_data"],
      "additional": {}
    },
    "summary": {
      "datasets_total": 1,
      "datasets_queued": 0,
      "datasets_processing": 0,
      "datasets_completed": 1,
      "datasets_failed": 0
    },
    "cost": {
      "total": 0.05,
      "refunded": 0
    },
    "timing": {
      "total": 0.83
    }
  }
}

​
Campos de data

CampoTipoDescrição
search_idstringID do histórico da consulta.
targetstringTipo público da consulta: person, company, process ou vehicle.
statusstringStatus técnico da consulta no momento do evento.
queryobjectParâmetros usados na consulta.
summaryobjectResumo de status dos datasets solicitados.
costobjectTotal debitado e valor estornado, quando disponível.
timingobjectTempo total da consulta, quando disponível.
errorsobjectErros técnicos por dataset ou falha principal, quando ocorrerem.

​
Campo query

CampoQuando aparece
taxidConsultas por CPF ou CNPJ.
plateConsultas veiculares.
datasetsSempre que datasets forem informados.
additionalQuando campos adicionais foram enviados.

​
Campo summary

CampoDescrição
datasets_totalQuantidade total de datasets considerados.
datasets_queuedQuantidade de datasets em fila.
datasets_processingQuantidade de datasets em processamento.
datasets_completedQuantidade de datasets concluídos.
datasets_failedQuantidade de datasets com falha.

​
Exemplo com erro parcial

{
  "id": "evt_49f2fd47-098b-4d52-b435-3ce5a65e5831",
  "event": "search.completed",
  "scope": "search",
  "created_at": "2026-06-23T12:01:00Z",
  "data": {
    "search_id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "target": "person",
    "status": "completed_with_errors",
    "query": {
      "taxid": "00000000000",
      "datasets": ["person_basic_data", "person_example_dataset"]
    },
    "summary": {
      "datasets_total": 2,
      "datasets_queued": 0,
      "datasets_processing": 0,
      "datasets_completed": 1,
      "datasets_failed": 1
    },
    "cost": {
      "total": 0.05,
      "refunded": 0.05
    },
    "errors": {
      "person_example_dataset": {
        "code": 42025,
        "message": "Não foi possível consultar o provedor da consulta."
      }
    }
  }
}

​
Como consumir

  1. Valide o header X-LazyData-Webhook-Signature.
  2. Use id para idempotência.
  3. Use event para rotear o tratamento.
  4. Use data.search_id para buscar o detalhe completo no histórico, quando necessário.
  5. Trate search.completed com data.status igual a completed_with_errors como conclusão com falha parcial.
Não use o webhook como fonte única de verdade para dados completos de datasets. O payload é um resumo operacional; consulte o histórico da API quando precisar do retorno completo.

​
Relacionado

Resultado assíncrono

Consulte o andamento e resultado de uma consulta assíncrona.

Histórico de consultas

Entenda status, custos, estornos e erros por dataset.