Skip to main content
Os webhooks permitem receber eventos da Lazy Data em um endpoint da sua aplicação. Use esse recurso quando você precisa reagir automaticamente a mudanças em consultas, enriquecimentos, validações, monitoramentos ou arquivos, sem depender apenas de polling ou conferência manual no painel. No painel, acesse Integrações > Webhook para cadastrar URLs de destino, escolher escopos e gerenciar a assinatura.

​
Quando usar

Use webhooks para:
  • atualizar sistemas internos quando uma consulta terminar;
  • acompanhar o andamento de enriquecimentos em massa;
  • receber o resultado de validações executadas pela API;
  • reagir a novidades de monitoramento;
  • sincronizar eventos de arquivos e pastas do armazenamento.
Webhooks são notificações de saída. Eles não substituem os endpoints de consulta, histórico, enriquecimento, validação, monitoramento ou armazenamento.

​
Como funciona

1

Cadastre pelo painel

No menu Webhook, informe nome, URL HTTPS de destino e os escopos que devem enviar eventos para esse webhook.
2

Receba a assinatura

Depois do cadastro, a Lazy Data gera um token de assinatura para aquele webhook.
3

Valide o header

Cada chamada enviada ao seu endpoint inclui o token no header X-LazyData-Webhook-Signature.
4

Processe o evento

Leia o campo event para identificar o tipo do evento e o objeto data para acessar os dados principais.

​
Escopos disponíveis

Ao cadastrar um webhook pelo painel, você seleciona escopos globais. Cada escopo envia todos os eventos relacionados ao produto correspondente.
EscopoMenu relacionadoQuando envia eventos
searchConsultasConsultas síncronas, assíncronas e histórico técnico.
enrichmentEnriquecimentoCriação, upload de arquivo, fila, processamento, conclusão e falhas.
validationValidaçõesConclusão ou falha de validações reais.
monitoringMonitoramentoCriação, checagens, novidades, pausas, retomadas, cancelamentos e falhas.
storageArmazenamentoCriação, upload, renomeação, exclusão e falhas de exclusão de itens.
Os eventos são agregados por produto. A Lazy Data não envia eventos individuais por dataset, linha de enriquecimento ou fonte interna para evitar excesso de requisições.

​
Contrato base

Todos os webhooks seguem a mesma regra de entrega:
  • a chamada é feita com método POST;
  • o corpo é enviado em JSON;
  • o tipo do evento aparece no header e no campo event;
  • a assinatura é enviada por header;
  • o payload sempre usa o mesmo envelope base;
  • os campos específicos ficam dentro de data.
A visão geral documenta o contrato comum. Eventos, payloads e campos específicos devem ser detalhados nas páginas de cada menu do produto.

​
Headers enviados

Cada webhook é enviado por POST para a URL cadastrada. Headers principais:
HeaderDescrição
X-LazyData-Webhook-SignatureToken de assinatura gerado para o webhook.
X-LazyData-Webhook-EventNome do evento enviado.
X-LazyData-Webhook-IdID único do evento.
User-AgentIdentificação do emissor Lazy Data.
Trate o token de assinatura como segredo. Se houver suspeita de exposição, gere uma nova assinatura no painel.

​
Estrutura do payload

Todos os eventos usam o mesmo envelope: 
{
  "id": "evt_6eb3d0a8-9e75-4a3f-9b6e-8d7fb86df01a",
  "event": "search.completed",
  "scope": "search",
  "created_at": "2026-06-23T12:00:00Z",
  "data": {}
}
Campos:
CampoDescrição
idIdentificador único do evento.
eventTipo do evento.
scopeEscopo que originou o evento.
created_atData de criação do evento em ISO 8601.
dataObjeto com dados mínimos do produto relacionado.

​
Campo data

O campo data varia conforme o escopo. Ele deve conter apenas dados úteis para identificar o recurso, entender o status do evento e buscar detalhes completos na API ou no painel quando necessário. Exemplos de chaves por escopo:
EscopoChave comum em dataConteúdo esperado
searchcampos diretosID da consulta, tipo, status, resumo de datasets, custos e erros principais.
enrichmentenrichmentID do enriquecimento, status, arquivo, progresso, custos e saídas disponíveis.
validationvalidationTipo de validação, status, resultado ou erro.
monitoringmonitoringID do monitoramento, alvo, status, checagens e novidade detectada.
storageitemItem afetado, tipo, nome, status e metadados básicos.
Quando o evento trouxer apenas um resumo, use o ID recebido para consultar o detalhe no endpoint ou tela do produto correspondente.

​
Tutoriais por escopo

Use os tutoriais específicos para ver eventos disponíveis, payloads completos, campos do objeto data e exemplos de tratamento por produto.

Webhook de consultas

Eventos de consultas síncronas, assíncronas, histórico e payloads de resultado.

Webhook de enriquecimento

Eventos de upload, análise, fila, processamento, conclusão e falhas.

Webhook de validações

Eventos de validação facial, validação cadastral, conclusão e falhas.

Webhook de monitoramento

Eventos de checagem, novidade detectada, pausa, retomada e cancelamento.

Webhook de armazenamento

Eventos de pastas, arquivos, upload, renomeação, exclusão e falhas.

​
Tempo de resposta

O envio do webhook é executado em background e não bloqueia a operação principal. A requisição para o endpoint cadastrado possui timeout de 30 segundos. Se houver mais de um webhook cadastrado para o mesmo escopo, a Lazy Data envia o evento para todos os endpoints ativos daquele escopo.

​
Boas práticas

  • use uma URL HTTPS pública e estável;
  • responda rapidamente com status 2xx;
  • valide o header X-LazyData-Webhook-Signature;
  • use o campo id para idempotência;
  • não dependa da ordem absoluta entre eventos de produtos diferentes;
  • armazene apenas os dados necessários para auditoria;
  • busque detalhes completos pela API quando o payload do webhook trouxer apenas resumo.

​
Próximos passos

Consultas

Veja eventos e payloads de consultas.

Enriquecimento

Veja eventos e payloads de enriquecimento.

Validações

Veja eventos e payloads de validações.

Monitoramento

Veja eventos e payloads de monitoramento.

Armazenamento

Veja eventos e payloads de armazenamento.