Saltar para o conteúdo principal

​
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:
  1. Você faz um POST de uma requisição de busca com uma URL de webhook nas settings
  2. A Enrow retorna um ID de busca imediatamente
  3. A Enrow processa a busca em segundo plano
  4. 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:
  1. Por requisição: Inclua uma URL de webhook no objeto settings de qualquer chamada de API
  2. Global: Configure um webhook padrão na página de integrações do painel
{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "settings": {
    "webhook": "https://your-app.com/webhooks/enrow"
  }
}
Sua URL de webhook deve ser um endpoint HTTPS válido que retorne um código de status 200.

​
Quais eventos disparam uma chamada de webhook?

Seis tipos de eventos podem disparar uma chamada de webhook, um por endpoint e tipo de busca:
EventDescrição
single_search_finishedUma busca de e-mail individual foi concluída
bulk_search_finishedUma busca de e-mail em massa foi concluída
verification_finishedUma verificação de e-mail individual foi concluída
bulk_verification_finishedUma verificação de e-mail em massa foi concluída
single_phone_search_finishedUma busca de telefone individual foi concluída
bulk_phone_search_finishedUma 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"
    }
  }
}

​
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",
  "credits": {
    "cost": 50
  },
  "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.
TipoBuscas individuaisBuscas em massa
PayloadResultado completo incluídoApenas notificação (ID + créditos)
GET necessário?NãoSim — 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, aceita apenas HTTPS e tolera duplicatas ocasionais. Siga estas práticas para manter as entregas confiáveis:
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.
Sempre use endpoints HTTPS. Webhooks via HTTP serão rejeitados.
Em casos raros, os webhooks podem ser entregues mais de uma vez. Use o campo id para fazer a deduplicação.
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.
WebhooksPolling (GET)
LatênciaTempo realDepende do intervalo de polling
Chamadas de API0 (a Enrow chama você)Várias chamadas por busca
Impacto no limite de taxaNenhumConsome a cota
ComplexidadeRequer configuração de endpointMais simples de implementar
Recomendamos webhooks para uso em produção. Use polling apenas para prototipagem rápida ou depuração.

​
FAQ

Não. Os webhooks não consomem créditos adicionais — você paga apenas pela busca em si. O custo em créditos é informado no campo credits.cost do payload. Consulte Créditos e cobrança para ver os custos por endpoint.
Sua URL de webhook deve ser um endpoint HTTPS válido que retorne um código de status 200. Se o seu servidor estiver inacessível ou responder com outro status, a entrega é considerada como falha. Como alternativa, você sempre pode recuperar os resultados consultando o endpoint GET correspondente com o id da busca.
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.
As causas mais comuns são uma URL que não usa HTTPS, um endpoint que não retorna 200 ou um servidor que atinge o tempo limite. Confirme que seu endpoint está acessível publicamente por HTTPS. 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.