Fonctionnement des webhooks - Enrow API Documentation

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 : configurez un webhook par défaut depuis la page des intégrations du tableau de bord

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

L’URL de votre webhook doit être un endpoint HTTPS valide qui renvoie un code de statut 200.

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"
    }
  }
}

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",
  "credits": {
    "cost": 50
  },
  "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 + crédits)
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, n’accepte que le 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 toujours des endpoints HTTPS. Les webhooks HTTP seront rejetés.

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. Le coût en crédits est indiqué dans le champ credits.cost de la charge utile. 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 ?

L’URL de votre webhook doit être un endpoint HTTPS valide qui renvoie un code de statut 200. Si votre serveur est injoignable ou répond avec un autre statut, la livraison est considérée comme échouée. En solution de repli, 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 une URL non HTTPS, un endpoint qui ne renvoie pas 200, ou un serveur qui expire. Vérifiez que votre endpoint est accessible publiquement en HTTPS. 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.

​Pourquoi utiliser les webhooks ?

​Comment fonctionne un flux de webhook ?

​Comment configurer un webhook ?

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

​À quoi ressemble une charge utile de webhook ?

​Email Finder — Unique

​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 ?

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

À quoi ressemble une charge utile de webhook ?

Email Finder — Unique

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