Cómo funcionan los webhooks

¿Por qué usar webhooks?

Los webhooks permiten que los resultados lleguen a ti en lugar de tener que pedirlos una y otra vez. En vez de consultar un endpoint GET hasta que una búsqueda termine, Enrow envía cada resultado a tu servidor en el momento en que está listo, lo que ahorra solicitudes, reduce la latencia y mantiene tu código simple. Deja de desperdiciar solicitudes: que los resultados lleguen a ti. Como cada endpoint de Enrow es asíncrono, los webhooks son la forma recomendada de recibir resultados en Email Finder, Email Verifier y Phone Finder. Los webhooks también evitan por completo los límites de tasa, ya que es Enrow quien te llama y no al revés.

¿Cómo funciona un flujo de webhook?

Un flujo de webhook convierte una sola solicitud de búsqueda en una entrega automática. Le indicas a Enrow dónde enviar los resultados y Enrow hace el resto:

Haces un POST con una solicitud de búsqueda que incluye una URL de webhook en los settings
Enrow devuelve un ID de búsqueda de inmediato
Enrow procesa la búsqueda en segundo plano
Cuando termina, Enrow envía los resultados mediante POST a tu URL de webhook

¿Cómo configuro un webhook?

Puedes registrar un webhook de dos maneras, según si lo quieres para una búsqueda o para todas:

Por solicitud: Incluye una URL de webhook en el objeto settings de cualquier llamada a la API
Global: Configura un webhook predeterminado en la página de API del panel. Enrow comprueba la URL al guardarla: consulta ¿Cómo verifico mi endpoint de webhook?

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

Cuando una solicitud incluye su propio webhook, lo que ocurre con el predeterminado depende del endpoint:

Email Finder: Enrow notifica a ambas URLs (una sola vez si son la misma)
Phone Finder y Email Verifier: la URL por solicitud reemplaza a la predeterminada

Tu endpoint de webhook debe ser accesible públicamente y devolver un código de estado 2xx. Usa HTTPS: las URLs en HTTP simple se aceptan, pero no se recomiendan. Enrow envía cada notificación una sola vez y no reintenta una entrega fallida, pero siempre puedes recurrir al endpoint GET correspondiente.

¿Cómo verifico mi endpoint de webhook?

Cuando guardas una nueva URL de webhook predeterminada en la página de API, Enrow primero le envía una solicitud de verificación única para confirmar que controlas el endpoint. La URL solo se guarda si tu endpoint responde correctamente a esa solicitud. Enrow envía una solicitud POST con este cuerpo JSON:

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

Tu endpoint debe responder en menos de 5 segundos con un código de estado 2xx y devolver el mismo valor de challenge, ya sea como cuerpo de la respuesta en bruto o en JSON:

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

Por ejemplo, con Node.js y 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
});

Si la comprobación falla, la aplicación muestra el motivo (sin respuesta en 5 segundos, un estado distinto de 2xx, un challenge que no coincide, una URL inaccesible o una dirección privada o interna) y tu webhook actual sigue activo. Un webhook pasado en los settings de una solicitud no se comprueba de esta manera.

¿Qué eventos activan una llamada de webhook?

Seis tipos de eventos pueden activar una llamada de webhook, uno por endpoint y tipo de búsqueda:

Evento	Descripción
`single_search_finished`	Una búsqueda de un solo email ha finalizado
`bulk_search_finished`	Una búsqueda masiva de emails ha finalizado
`verification_finished`	Una verificación de un solo email ha finalizado
`bulk_verification_finished`	Una verificación masiva de emails ha finalizado
`single_phone_search_finished`	Una búsqueda de un solo teléfono ha finalizado
`bulk_phone_search_finished`	Una búsqueda masiva de teléfonos ha finalizado

¿Qué aspecto tiene un payload de webhook?

El payload del webhook depende del endpoint y de si la búsqueda fue individual o masiva. Las búsquedas individuales entregan el resultado completo directamente, mientras que las búsquedas masivas entregan una notificación de finalización que debes complementar con una solicitud GET.

Email Finder — Individual

En las búsquedas individuales, recibes el resultado completo directamente en la notificación del webhook. Esto elimina la necesidad de realizar una solicitud 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"
    }
  }
}

Búsqueda a partir de una URL de perfil de LinkedIn

En una búsqueda lanzada a partir de una URL de perfil de LinkedIn, result incluye además linkedin_status y linkedin_url (la URL que enviaste). info solo se incluye si se encuentra un email: una búsqueda sin resultado nunca nombra a la persona. credits.cost es el costo final, como credits_used en la respuesta GET, que también 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 — Masivo

En las búsquedas masivas, recibes una notificación de que el lote ha finalizado. Luego llama al endpoint GET /email/find/bulk con el id para recuperar los resultados.

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

Email Verifier — Individual

El resultado completo se incluye directamente: no se necesita ninguna solicitud GET.

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

Email Verifier — Masivo

Esto es solo una notificación. Llama a GET /email/verify/bulk con el id para recuperar los resultados.

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

Phone Finder — Individual

El resultado completo se incluye directamente: no se necesita ninguna solicitud 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 — Masivo

Esto es solo una notificación. Llama a GET /phone/bulk con el id para recuperar los resultados.

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

¿En qué se diferencian los webhooks individuales y masivos?

Los webhooks de búsqueda individual contienen el resultado completo, por lo que no se necesita ninguna llamada adicional. Los webhooks de búsqueda masiva solo indican que el lote ha terminado: luego recuperas los resultados con el endpoint GET correspondiente.

Tipo	Búsquedas individuales	Búsquedas masivas
Payload	Resultado completo incluido	Solo notificación (ID, más los créditos salvo en las búsquedas de teléfono)
¿Se necesita GET?	No	Sí, usa el endpoint GET con el `id`

En las búsquedas individuales, el webhook contiene todo lo que necesitas. En las búsquedas masivas, el webhook te indica que el lote ha terminado y luego recuperas los resultados.

¿Cuáles son las mejores prácticas para los endpoints de webhook?

Un endpoint de webhook fiable responde rápido, usa HTTPS y tolera algún duplicado ocasional. Sigue estas prácticas para que las entregas sean confiables:

Devuelve 200 rápidamente

Procesa los payloads de los webhooks de forma asíncrona. Devuelve un 200 de inmediato y luego maneja los datos en una tarea en segundo plano.

Usa HTTPS

Usa un endpoint HTTPS para que los resultados viajen cifrados. Las URLs en HTTP simple se aceptan, pero no se recomiendan.

Gestiona los duplicados

En casos poco frecuentes, los webhooks pueden entregarse más de una vez. Usa el campo id para eliminar duplicados.

Usa campos personalizados

Pasa datos en custom en tus solicitudes para identificar a qué registro pertenece el resultado de un webhook:

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

El campo custom se devuelve tal cual en el payload del webhook.

¿Debo usar webhooks o polling?

Usa webhooks en producción y polling solo para prototipado rápido o depuración. Los webhooks entregan resultados en tiempo real sin consumir tu cuota de solicitudes, mientras que el polling realiza llamadas GET repetidas que cuentan para tus límites de tasa.

	Webhooks	Polling (GET)
Latencia	En tiempo real	Depende del intervalo de consulta
Llamadas a la API	0 (Enrow te llama)	Varias llamadas por búsqueda
Impacto en el límite de tasa	Ninguno	Consume cuota
Complejidad	Requiere configurar un endpoint	Más simple de implementar

Recomendamos los webhooks para uso en producción. Usa polling solo para prototipado rápido o depuración.

FAQ

¿Los webhooks cuestan créditos adicionales?

No. Los webhooks no consumen créditos adicionales: solo pagas por la búsqueda en sí. En los payloads de Email Finder y Email Verifier, el costo en créditos se informa en el campo credits.cost. Es el costo final, una vez aplicados los reembolsos: 0 para una búsqueda individual sin resultado (0.25 para una búsqueda de email a partir de una URL de perfil de LinkedIn o para una cuenta con una tasa de éxito anormalmente baja) y, para una búsqueda masiva, las filas encontradas más los fallos cobrados. Los payloads de Phone Finder no incluyen el costo. Consulta Créditos y facturación para ver los costos por endpoint.

¿Qué ocurre si mi endpoint no devuelve un 200?

Enrow envía cada notificación una sola vez. Si tu servidor es inaccesible o responde con un estado distinto de 2xx, la entrega falla y no se reintenta. Siempre puedes recuperar los resultados consultando el endpoint GET correspondiente con el id de la búsqueda.

¿Cómo asocio un webhook con la solicitud original?

Usa el id de la respuesta de búsqueda, o pasa un objeto custom en tu solicitud: se devuelve tal cual en el payload del webhook para que puedas mapear los resultados con tus propios registros, como el ID de un lead de tu CRM.

¿Por qué no recibí un webhook?

Las causas más comunes son un endpoint que no devuelve 2xx, un servidor que agota el tiempo de espera o una URL que no es accesible públicamente. Las entregas fallidas no se reintentan: recupera el resultado con el endpoint GET correspondiente y el id de la búsqueda. Para una resolución de problemas más amplia, consulta Manejo de errores y Códigos de estado.

Próximos pasos

Buscar un email

Pasa una URL de webhook en settings para recibir el resultado de forma automática.

Obtener resultados masivos

Recupera los resultados del lote después de que se dispare un webhook bulk_search_finished.

Autenticación

Cómo pasar tu clave de API en la cabecera x-api-key.

Límites de tasa

Descubre por qué los webhooks evitan la cuota de solicitudes que consume el polling.

Primeros pasos

Email Finder

Email Verifier

Phone Finder

Cuenta

¿Por qué usar webhooks?

¿Cómo funciona un flujo de webhook?

¿Cómo configuro un webhook?

¿Cómo verifico mi endpoint de webhook?

¿Qué eventos activan una llamada de webhook?

¿Qué aspecto tiene un payload de webhook?

Email Finder — Individual

Búsqueda a partir de una URL de perfil de LinkedIn

Email Finder — Masivo

Email Verifier — Individual

Email Verifier — Masivo

Phone Finder — Individual

Phone Finder — Masivo

¿En qué se diferencian los webhooks individuales y masivos?

¿Cuáles son las mejores prácticas para los endpoints de webhook?

¿Debo usar webhooks o polling?

FAQ

Próximos pasos

Buscar un email

Obtener resultados masivos

Autenticación

Límites de tasa

​¿Por qué usar webhooks?

​¿Cómo funciona un flujo de webhook?

​¿Cómo configuro un webhook?

​¿Cómo verifico mi endpoint de webhook?

​¿Qué eventos activan una llamada de webhook?

​¿Qué aspecto tiene un payload de webhook?

​Email Finder — Individual

​Búsqueda a partir de una URL de perfil de LinkedIn

​Email Finder — Masivo

​Email Verifier — Individual

​Email Verifier — Masivo

​Phone Finder — Individual

​Phone Finder — Masivo

​¿En qué se diferencian los webhooks individuales y masivos?

​¿Cuáles son las mejores prácticas para los endpoints de webhook?

​¿Debo usar webhooks o polling?

​FAQ

​Próximos pasos

Buscar un email

Obtener resultados masivos

Autenticación

Límites de tasa

¿Por qué usar webhooks?

¿Cómo funciona un flujo de webhook?

¿Cómo configuro un webhook?

¿Cómo verifico mi endpoint de webhook?

¿Qué eventos activan una llamada de webhook?

¿Qué aspecto tiene un payload de webhook?

Email Finder — Individual

Búsqueda a partir de una URL de perfil de LinkedIn

Email Finder — Masivo

Email Verifier — Individual

Email Verifier — Masivo

Phone Finder — Individual

Phone Finder — Masivo

¿En qué se diferencian los webhooks individuales y masivos?

¿Cuáles son las mejores prácticas para los endpoints de webhook?

¿Debo usar webhooks o polling?

FAQ

Próximos pasos