Fonctionnement des webhooks

Pourquoi utiliser les webhooks ?

Les webhooks font venir les résultats à vous au lieu de vous obliger à les demander sans cesse. Plutôt que d’interroger en boucle un endpoint GET jusqu’à la fin d’une recherche, Enrow envoie chaque résultat à votre serveur dès qu’il est prêt, ce qui économise des requêtes, réduit la latence et garde votre code simple. Arrêtez de gaspiller des requêtes : laissez les résultats venir à vous. Comme chaque endpoint Enrow est asynchrone, les webhooks sont le moyen recommandé pour recevoir les résultats sur Email Finder, Email Verifier et Phone Finder. Les webhooks contournent également entièrement les limites de débit, puisque c’est Enrow qui vous appelle et non l’inverse.

Comment fonctionne un flux de webhook ?

Un flux de webhook transforme une simple requête de recherche en une livraison automatique. Vous indiquez à Enrow où envoyer les résultats, et Enrow se charge du reste :

Vous envoyez en POST une requête de recherche avec une URL webhook dans les settings
Enrow renvoie immédiatement un ID de recherche
Enrow traite la recherche en arrière-plan
Une fois terminée, Enrow envoie en POST les résultats vers l’URL de votre webhook

Comment configurer un webhook ?

Vous pouvez enregistrer un webhook de deux manières, selon que vous le souhaitez pour une seule recherche ou pour toutes les recherches :

Par requête : incluez une URL webhook dans l’objet settings de n’importe quel appel d’API
Globale : définissez un webhook par défaut sur la page API du tableau de bord. Enrow vérifie l’URL au moment où vous l’enregistrez : consultez Comment vérifier mon endpoint de webhook ?

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

Lorsqu’une requête inclut son propre webhook, ce qu’il advient du webhook par défaut dépend de l’endpoint :

Email Finder : Enrow notifie les deux URL (une seule fois si elles sont identiques)
Phone Finder et Email Verifier : l’URL de la requête remplace celle par défaut

Votre endpoint de webhook doit être accessible publiquement et renvoyer un code de statut 2xx. Utilisez HTTPS : les URL en HTTP simple sont acceptées, mais déconseillées. Enrow envoie chaque notification une seule fois et ne relance pas une livraison échouée : vous pouvez toujours vous rabattre sur l’endpoint GET correspondant.

Comment vérifier mon endpoint de webhook ?

Lorsque vous enregistrez une nouvelle URL de webhook par défaut sur la page API, Enrow lui envoie d’abord une requête de vérification ponctuelle pour confirmer que vous contrôlez l’endpoint. L’URL n’est enregistrée que si votre endpoint y répond correctement. Enrow envoie une requête POST avec ce corps JSON :

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

Votre endpoint doit répondre dans les 5 secondes avec un code de statut 2xx et renvoyer la même valeur challenge, soit telle quelle dans le corps de la réponse, soit en JSON :

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

Par exemple, avec Node.js et 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 vérification échoue, l’application en indique la raison (pas de réponse dans les 5 secondes, un statut autre que 2xx, un challenge qui ne correspond pas, une URL injoignable, ou une adresse privée ou interne) et votre webhook actuel reste actif. Un webhook transmis dans les settings d’une requête n’est pas vérifié de cette façon.

Quels événements déclenchent un appel de webhook ?

Six types d’événements peuvent déclencher un appel de webhook, un par endpoint et par type de recherche :

Event	Description
`single_search_finished`	Une recherche d’e-mail unique est terminée
`bulk_search_finished`	Une recherche d’e-mails en masse est terminée
`verification_finished`	Une vérification d’e-mail unique est terminée
`bulk_verification_finished`	Une vérification d’e-mails en masse est terminée
`single_phone_search_finished`	Une recherche de téléphone unique est terminée
`bulk_phone_search_finished`	Une recherche de téléphones en masse est terminée

À quoi ressemble une charge utile de webhook ?

La charge utile du webhook dépend de l’endpoint et du caractère unique ou en masse de la recherche. Les recherches uniques livrent directement le résultat complet, tandis que les recherches en masse livrent une notification d’achèvement que vous complétez par une requête GET.

Email Finder — Unique

Pour les recherches uniques, vous recevez le résultat complet directement dans la notification du webhook. Cela évite d’avoir à effectuer une requête 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"
    }
  }
}

Recherche par URL de profil LinkedIn

Pour une recherche lancée à partir d’une URL de profil LinkedIn, result contient aussi linkedin_status et linkedin_url (l’URL que vous avez envoyée). info n’est inclus que si un e-mail est trouvé : une recherche qui ne trouve rien ne nomme jamais la personne. credits.cost est le coût final, comme credits_used dans la réponse GET, qui explique aussi chaque 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 — En masse

Pour les recherches en masse, vous recevez une notification indiquant que le lot est terminé. Appelez ensuite l’endpoint GET /email/find/bulk avec l’id pour récupérer les résultats.

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

Email Verifier — Unique

Le résultat complet est inclus directement, aucune requête GET n’est nécessaire.

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

Email Verifier — En masse

Il s’agit uniquement d’une notification. Appelez GET /email/verify/bulk avec l’id pour récupérer les résultats.

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

Phone Finder — Unique

Le résultat complet est inclus directement, aucune requête GET n’est nécessaire.

{
  "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 — En masse

Il s’agit uniquement d’une notification. Appelez GET /phone/bulk avec l’id pour récupérer les résultats.

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

Quelle différence entre les webhooks uniques et en masse ?

Les webhooks de recherche unique contiennent le résultat complet, aucun appel supplémentaire n’est donc nécessaire. Les webhooks de recherche en masse signalent uniquement que le lot est terminé : vous récupérez ensuite les résultats avec l’endpoint GET correspondant.

Type	Recherches uniques	Recherches en masse
Charge utile	Résultat complet inclus	Notification uniquement (ID, plus les crédits sauf pour les recherches de téléphone)
GET nécessaire ?	Non	Oui — utilisez l’endpoint GET avec l’`id`

Pour les recherches uniques, le webhook contient tout ce dont vous avez besoin. Pour les recherches en masse, le webhook vous indique que le lot est terminé, puis vous récupérez les résultats.

Quelles sont les bonnes pratiques pour les endpoints de webhook ?

Un endpoint de webhook fiable répond rapidement, utilise HTTPS et tolère les doublons occasionnels. Suivez ces pratiques pour garder des livraisons fiables :

Renvoyez 200 rapidement

Traitez les charges utiles des webhooks de manière asynchrone. Renvoyez immédiatement un 200, puis traitez les données dans une tâche en arrière-plan.

Utilisez HTTPS

Utilisez un endpoint HTTPS pour que les résultats circulent chiffrés. Les URL en HTTP simple sont acceptées, mais déconseillées.

Gérez les doublons

Dans de rares cas, les webhooks peuvent être livrés plus d’une fois. Utilisez le champ id pour dédupliquer.

Utilisez des champs personnalisés

Transmettez des données custom dans vos requêtes pour identifier l’enregistrement auquel correspond un résultat de webhook :

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

Le champ custom est renvoyé tel quel dans la charge utile du webhook.

Faut-il utiliser les webhooks ou le polling ?

Utilisez les webhooks en production et le polling uniquement pour du prototypage rapide ou du débogage. Les webhooks livrent les résultats en temps réel sans consommer votre quota de requêtes, tandis que le polling effectue des appels GET répétés qui sont décomptés de vos limites de débit.

	Webhooks	Polling (GET)
Latence	Temps réel	Dépend de l’intervalle d’interrogation
Appels d’API	0 (Enrow vous appelle)	Plusieurs appels par recherche
Impact sur la limite de débit	Aucun	Consomme du quota
Complexité	Nécessite la configuration d’un endpoint	Plus simple à mettre en œuvre

Nous recommandons les webhooks pour une utilisation en production. N’utilisez le polling que pour le prototypage rapide ou le débogage.

FAQ

Les webhooks coûtent-ils des crédits supplémentaires ?

Non. Les webhooks ne consomment pas de crédits supplémentaires : vous ne payez que pour la recherche elle-même. Les charges utiles Email Finder et Email Verifier indiquent le coût en crédits dans le champ credits.cost. C’est le coût final, remboursements faits : 0 pour une recherche unitaire qui n’a rien trouvé (0.25 pour une recherche d’email à partir d’une URL de profil LinkedIn ou pour un compte au taux de succès anormalement bas) et, pour une recherche groupée, les lignes trouvées plus les échecs débités. Les charges utiles Phone Finder n’incluent pas le coût. Consultez Crédits et facturation pour connaître les coûts par endpoint.

Que se passe-t-il si mon endpoint ne renvoie pas un 200 ?

Enrow envoie chaque notification une seule fois. Si votre serveur est injoignable ou répond avec un statut autre que 2xx, la livraison échoue et n’est pas relancée. Vous pouvez toujours récupérer les résultats en interrogeant l’endpoint GET concerné avec l’id de la recherche.

Comment associer un webhook à la requête d'origine ?

Utilisez l’id de la réponse de recherche, ou transmettez un objet custom dans votre requête : il est renvoyé tel quel dans la charge utile du webhook, ce qui vous permet de relier les résultats à vos propres enregistrements, comme un identifiant de lead CRM.

Pourquoi n'ai-je pas reçu de webhook ?

Les causes les plus fréquentes sont un endpoint qui ne renvoie pas 2xx, un serveur qui expire, ou une URL qui n’est pas accessible publiquement. Les livraisons échouées ne sont pas relancées : récupérez le résultat avec l’endpoint GET correspondant et l’id de la recherche. Pour un dépannage plus approfondi, consultez Gestion des erreurs et Codes de statut.

Étapes suivantes

Trouver un e-mail

Transmettez une URL de webhook dans les settings pour recevoir le résultat automatiquement.

Récupérer des résultats en masse

Récupérez les résultats du lot après le déclenchement d’un webhook bulk_search_finished.

Authentification

Comment transmettre votre clé API dans l’en-tête x-api-key.

Limites de débit

Découvrez pourquoi les webhooks évitent le quota de requêtes que le polling consomme.

Démarrage

Email Finder

Email Verifier

Phone Finder

Compte

Pourquoi utiliser les webhooks ?

Comment fonctionne un flux de webhook ?

Comment configurer un webhook ?

Comment vérifier mon endpoint de webhook ?

Quels événements déclenchent un appel de webhook ?

À quoi ressemble une charge utile de webhook ?

Email Finder — Unique

Recherche par URL de profil LinkedIn

Email Finder — En masse

Email Verifier — Unique

Email Verifier — En masse

Phone Finder — Unique

Phone Finder — En masse

Quelle différence entre les webhooks uniques et en masse ?

Quelles sont les bonnes pratiques pour les endpoints de webhook ?

Faut-il utiliser les webhooks ou le polling ?

FAQ

Étapes suivantes

Trouver un e-mail

Récupérer des résultats en masse

Authentification

Limites de débit

​Pourquoi utiliser les webhooks ?

​Comment fonctionne un flux de webhook ?

​Comment configurer un webhook ?

​Comment vérifier mon endpoint de webhook ?

​Quels événements déclenchent un appel de webhook ?

​À quoi ressemble une charge utile de webhook ?

​Email Finder — Unique

​Recherche par URL de profil LinkedIn

​Email Finder — En masse

​Email Verifier — Unique

​Email Verifier — En masse

​Phone Finder — Unique

​Phone Finder — En masse

​Quelle différence entre les webhooks uniques et en masse ?

​Quelles sont les bonnes pratiques pour les endpoints de webhook ?

​Faut-il utiliser les webhooks ou le polling ?

​FAQ

​Étapes suivantes

Trouver un e-mail

Récupérer des résultats en masse

Authentification

Limites de débit

Pourquoi utiliser les webhooks ?

Comment fonctionne un flux de webhook ?

Comment configurer un webhook ?

Comment vérifier mon endpoint de webhook ?

Quels événements déclenchent un appel de webhook ?

À quoi ressemble une charge utile de webhook ?

Email Finder — Unique

Recherche par URL de profil LinkedIn

Email Finder — En masse

Email Verifier — Unique

Email Verifier — En masse

Phone Finder — Unique

Phone Finder — En masse

Quelle différence entre les webhooks uniques et en masse ?

Quelles sont les bonnes pratiques pour les endpoints de webhook ?

Faut-il utiliser les webhooks ou le polling ?

FAQ

Étapes suivantes