Como funcionam os webhooks

Por que usar webhooks?

Os webhooks fazem com que os resultados cheguem até você, em vez de você ter que pedi-los repetidamente. Em vez de consultar um endpoint GET até que uma busca termine, a Enrow envia cada resultado para o seu servidor no momento em que ele está pronto — economizando requisições, reduzindo a latência e mantendo seu código simples. Pare de desperdiçar requisições — deixe os resultados chegarem até você. Como todos os endpoints da Enrow são assíncronos, os webhooks são a forma recomendada de receber resultados em Email Finder, Email Verifier e Phone Finder. Os webhooks também ignoram completamente os limites de taxa, já que é a Enrow quem chama você, e não o contrário.

Como funciona um fluxo de webhook?

Um fluxo de webhook transforma uma única requisição de busca em uma entrega automática. Você diz à Enrow para onde enviar os resultados, e a Enrow faz o resto:

Você faz um POST de uma requisição de busca com uma URL de webhook nas settings
A Enrow retorna um ID de busca imediatamente
A Enrow processa a busca em segundo plano
Quando concluída, a Enrow faz um POST dos resultados para a sua URL de webhook

Como configuro um webhook?

Você pode registrar um webhook de duas maneiras, dependendo se deseja usá-lo para uma busca ou para todas as buscas:

Por requisição: Inclua uma URL de webhook no objeto settings de qualquer chamada de API
Global: Defina um webhook padrão na página API do painel. A Enrow verifica a URL quando você a salva: consulte Como verifico meu endpoint de webhook?

{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "settings": {
    "webhook": "https://your-app.com/webhooks/enrow"
  }
}

Quando uma requisição inclui o próprio webhook, o que acontece com o webhook padrão depende do endpoint:

Email Finder: a Enrow notifica as duas URLs (uma única vez se forem iguais)
Phone Finder e Email Verifier: a URL por requisição substitui a URL padrão

Seu endpoint de webhook deve estar acessível publicamente e retornar um código de status 2xx. Use HTTPS: URLs HTTP simples são aceitas, mas não recomendadas. A Enrow envia cada notificação uma única vez e não repete uma entrega que falhou, então você sempre pode recorrer ao endpoint GET correspondente.

Como verifico meu endpoint de webhook?

Quando você salva uma nova URL de webhook padrão na página API, a Enrow envia antes uma única requisição de verificação a essa URL para confirmar que você controla o endpoint. A URL só é salva se o seu endpoint responder corretamente a essa requisição. A Enrow envia uma requisição POST com este corpo JSON:

{
  "event": "endpoint_verification",
  "challenge": "3f9c1e2a-7b4d-4c8e-9a51-2d6f0b7e8c13"
}

Seu endpoint deve responder em até 5 segundos com um código de status 2xx e devolver o mesmo valor de challenge, seja como corpo bruto da resposta, seja em JSON:

{
  "challenge": "3f9c1e2a-7b4d-4c8e-9a51-2d6f0b7e8c13"
}

Por exemplo, com Node.js e Express:

app.post('/webhooks/enrow', express.json(), (req, res) => {
  if (req.body.event === 'endpoint_verification') {
    return res.json({ challenge: req.body.challenge });
  }
  res.sendStatus(200);
  // Then process the result in the background
});

Se a verificação falhar, o app mostra o motivo (nenhuma resposta em até 5 segundos, um status diferente de 2xx, um challenge que não corresponde, uma URL inacessível ou um endereço privado ou interno) e o seu webhook atual continua ativo. Um webhook passado nas settings de uma requisição não é verificado dessa forma.

Quais eventos disparam uma chamada de webhook?

Seis tipos de eventos podem disparar uma chamada de webhook, um por endpoint e tipo de busca:

Event	Descrição
`single_search_finished`	Uma busca de e-mail individual foi concluída
`bulk_search_finished`	Uma busca de e-mail em massa foi concluída
`verification_finished`	Uma verificação de e-mail individual foi concluída
`bulk_verification_finished`	Uma verificação de e-mail em massa foi concluída
`single_phone_search_finished`	Uma busca de telefone individual foi concluída
`bulk_phone_search_finished`	Uma busca de telefone em massa foi concluída

Como é o payload de um webhook?

O payload do webhook depende do endpoint e de a busca ser individual ou em massa. Buscas individuais entregam o resultado completo diretamente, enquanto buscas em massa entregam uma notificação de conclusão que você complementa com uma requisição GET.

Email Finder — Individual

Para buscas individuais, você recebe o resultado completo diretamente na notificação do webhook. Isso elimina a necessidade de fazer uma requisição GET.

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 1
  },
  "result": {
    "email": "dwight.schrute@dundermifflin.com",
    "qualification": "valid",
    "custom": "your_custom_data",
    "info": {
      "company_domain": "dundermifflin.com",
      "fullname": "Dwight Schrute",
      "firstname": "Dwight",
      "lastname": "Schrute"
    }
  }
}

Busca a partir da URL de um perfil do LinkedIn

Em uma busca iniciada a partir da URL de um perfil do LinkedIn, result também traz linkedin_status e linkedin_url (a URL que você enviou). info só é incluído quando um email é encontrado: uma busca que não encontra nada nunca revela quem é a pessoa. credits.cost é o custo final, como credits_used na resposta do GET, que também explica cada linkedin_status.

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 1
  },
  "result": {
    "email": "dwight.schrute@dundermifflin.com",
    "qualification": "valid",
    "linkedin_status": "found",
    "linkedin_url": "https://www.linkedin.com/in/dwight-schrute",
    "custom": { "crm_id": "lead_001" },
    "info": {
      "company_domain": "dundermifflin.com",
      "company_name": "Dunder Mifflin",
      "fullname": "Dwight Schrute",
      "firstname": "Dwight",
      "lastname": "Schrute"
    }
  }
}

{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 0.25
  },
  "result": {
    "qualification": "invalid",
    "linkedin_status": "no_current_company",
    "linkedin_url": "https://www.linkedin.com/in/dwight-schrute",
    "custom": { "crm_id": "lead_001" }
  }
}

Email Finder — Em massa

Para buscas em massa, você recebe uma notificação de que o lote foi concluído. Em seguida, chame o endpoint GET /email/find/bulk com o id para recuperar os resultados.

{
  "event": "bulk_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 2284
  }
}

Email Verifier — Individual

O resultado completo é incluído diretamente — não é necessária uma requisição GET.

{
  "event": "verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "email": "pam.beesly@dundermifflin.com",
  "qualification": "valid",
  "custom": "your_custom_data"
}

Email Verifier — Em massa

Esta é apenas uma notificação. Chame GET /email/verify/bulk com o id para recuperar os resultados.

{
  "event": "bulk_verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 386.25
  }
}

Phone Finder — Individual

O resultado completo é incluído diretamente — não é necessária uma requisição GET.

{
  "event": "single_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "result": {
    "number": "+15705551234",
    "params": {
      "linkedin_url": "https://www.linkedin.com/in/michael-scott"
    },
    "qualification": "found"
  }
}

Phone Finder — Em massa

Esta é apenas uma notificação. Chame GET /phone/bulk com o id para recuperar os resultados.

{
  "event": "bulk_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt"
}

Qual a diferença entre webhooks individuais e em massa?

Os webhooks de busca individual contêm o resultado completo, então nenhuma chamada extra é necessária. Os webhooks de busca em massa apenas sinalizam que o lote foi concluído — em seguida, você busca os resultados com o endpoint GET correspondente.

Tipo	Buscas individuais	Buscas em massa
Payload	Resultado completo incluído	Apenas notificação (ID, mais os créditos, exceto nas buscas de telefone)
GET necessário?	Não	Sim — use o endpoint GET com o `id`

Para buscas individuais, o webhook contém tudo o que você precisa. Para buscas em massa, o webhook informa que o lote foi concluído — então você busca os resultados.

Quais são as boas práticas para endpoints de webhook?

Um endpoint de webhook confiável responde rapidamente, usa HTTPS e tolera duplicatas ocasionais. Siga estas práticas para manter as entregas confiáveis:

Retorne 200 rapidamente

Processe os payloads de webhook de forma assíncrona. Retorne um 200 imediatamente e, em seguida, trate os dados em uma tarefa em segundo plano.

Use HTTPS

Use um endpoint HTTPS para que os resultados trafeguem criptografados. URLs HTTP simples são aceitas, mas não recomendadas.

Trate duplicatas

Em casos raros, os webhooks podem ser entregues mais de uma vez. Use o campo id para fazer a deduplicação.

Use campos personalizados

Passe dados em custom nas suas requisições para identificar a qual registro pertence o resultado de um webhook:

{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "custom": { "crm_id": "lead_001" }
}

O campo custom é retornado inalterado no payload do webhook.

Devo usar webhooks ou polling?

Use webhooks em produção e polling apenas para prototipagem rápida ou depuração. Os webhooks entregam resultados em tempo real sem consumir sua cota de requisições, enquanto o polling faz chamadas GET repetidas que contam para os seus limites de taxa.

	Webhooks	Polling (GET)
Latência	Tempo real	Depende do intervalo de polling
Chamadas de API	0 (a Enrow chama você)	Várias chamadas por busca
Impacto no limite de taxa	Nenhum	Consome a cota
Complexidade	Requer configuração de endpoint	Mais simples de implementar

Recomendamos webhooks para uso em produção. Use polling apenas para prototipagem rápida ou depuração.

FAQ

Os webhooks custam créditos extras?

Não. Os webhooks não consomem créditos adicionais: você paga apenas pela busca em si. Os payloads do Email Finder e do Email Verifier informam o custo em créditos no campo credits.cost. É o custo final, já com os reembolsos: 0 para uma busca individual sem resultado (0.25 para uma busca de email a partir da URL de um perfil do LinkedIn ou para uma conta com taxa de sucesso anormalmente baixa) e, para uma busca em massa, as linhas encontradas mais as falhas cobradas. Os payloads do Phone Finder não incluem o custo. Consulte Créditos e cobrança para ver os custos por endpoint.

O que acontece se meu endpoint não retornar um 200?

A Enrow envia cada notificação uma única vez. Se o seu servidor estiver inacessível ou responder com um status diferente de 2xx, a entrega falha e não é repetida. Você sempre pode recuperar os resultados consultando o endpoint GET correspondente com o id da busca.

Como faço para associar um webhook à requisição original?

Use o id da resposta da busca ou passe um objeto custom na sua requisição — ele é retornado inalterado no payload do webhook, para que você possa mapear os resultados de volta aos seus próprios registros, como o ID de um lead no CRM.

Por que não recebi um webhook?

As causas mais comuns são um endpoint que não retorna 2xx, um servidor que atinge o tempo limite ou uma URL que não está acessível publicamente. As entregas que falham não são repetidas: recupere o resultado com o endpoint GET correspondente e o id da busca. Para uma solução de problemas mais ampla, consulte Tratamento de erros e Códigos de status.

Próximos passos

Encontrar um e-mail

Passe uma URL de webhook nas settings para receber o resultado automaticamente.

Obter resultados em massa

Busque os resultados do lote após o disparo de um webhook bulk_search_finished.

Autenticação

Como passar sua chave de API no cabeçalho x-api-key.

Limites de taxa

Veja por que os webhooks evitam a cota de requisições que o polling consome.

Primeiros passos

Email Finder

Email Verifier

Phone Finder

Conta

Por que usar webhooks?

Como funciona um fluxo de webhook?

Como configuro um webhook?

Como verifico meu endpoint de webhook?

Quais eventos disparam uma chamada de webhook?

Como é o payload de um webhook?

Email Finder — Individual

Busca a partir da URL de um perfil do LinkedIn

Email Finder — Em massa

Email Verifier — Individual

Email Verifier — Em massa

Phone Finder — Individual

Phone Finder — Em massa

Qual a diferença entre webhooks individuais e em massa?

Quais são as boas práticas para endpoints de webhook?

Devo usar webhooks ou polling?

FAQ

Próximos passos

Encontrar um e-mail

Obter resultados em massa

Autenticação

Limites de taxa

​Por que usar webhooks?

​Como funciona um fluxo de webhook?

​Como configuro um webhook?

​Como verifico meu endpoint de webhook?

​Quais eventos disparam uma chamada de webhook?

​Como é o payload de um webhook?

​Email Finder — Individual

​Busca a partir da URL de um perfil do LinkedIn

​Email Finder — Em massa

​Email Verifier — Individual

​Email Verifier — Em massa

​Phone Finder — Individual

​Phone Finder — Em massa

​Qual a diferença entre webhooks individuais e em massa?

​Quais são as boas práticas para endpoints de webhook?

​Devo usar webhooks ou polling?

​FAQ

​Próximos passos

Encontrar um e-mail

Obter resultados em massa

Autenticação

Limites de taxa

Por que usar webhooks?

Como funciona um fluxo de webhook?

Como configuro um webhook?

Como verifico meu endpoint de webhook?

Quais eventos disparam uma chamada de webhook?

Como é o payload de um webhook?

Email Finder — Individual

Busca a partir da URL de um perfil do LinkedIn

Email Finder — Em massa

Email Verifier — Individual

Email Verifier — Em massa

Phone Finder — Individual

Phone Finder — Em massa

Qual a diferença entre webhooks individuais e em massa?

Quais são as boas práticas para endpoints de webhook?

Devo usar webhooks ou polling?

FAQ

Próximos passos