En résumé : Les webhooks Rodz vous permettent de recevoir vos signaux d’affaires en temps réel, directement sur votre serveur. Plus besoin d’interroger l’API en boucle. Ce guide vous accompagne pas à pas, de la création de votre endpoint à la vérification de la signature HMAC, en passant par l’enregistrement de votre URL et le parsing des payloads.
Qu’est-ce qu’un webhook et pourquoi l’utiliser pour vos signaux d’affaires ?
Un webhook est un mécanisme de notification HTTP. Concrètement, c’est une requête POST que Rodz envoie automatiquement à une URL de votre choix chaque fois qu’un événement se produit. Dans le contexte des signaux d’affaires, cela signifie que vous recevez une notification instantanée dès qu’un signal correspond à votre configuration : levée de fonds, recrutement, déménagement, changement de dirigeant, ou tout autre événement que vous surveillez.
L’alternative classique, c’est le polling : interroger l’API à intervalles réguliers pour vérifier si de nouvelles données sont disponibles. Cette approche pose plusieurs problèmes. Vous consommez des appels API inutilement, vous introduisez un délai entre la détection du signal et votre réaction, et vous complexifiez votre code avec de la logique de pagination et de déduplication.
Avec les webhooks, le flux s’inverse. C’est Rodz qui vous contacte. Vous ne consommez aucune requête API, vous recevez le signal dans les secondes qui suivent sa détection, et votre code se résume à un simple endpoint HTTP qui traite les données entrantes.
Si vous n’avez pas encore configuré vos premiers signaux, commencez par lire le guide de configuration des signaux via l’API. Et si vous découvrez l’API Rodz, consultez d’abord le guide de démarrage et d’authentification.
Prérequis
Avant de commencer, assurez-vous d’avoir les éléments suivants :
- Une clé API Rodz active. Vous la trouverez dans votre tableau de bord. Si vous ne l’avez pas encore, suivez le guide d’authentification.
- Un endpoint HTTPS accessible publiquement. Votre serveur doit être joignable depuis Internet sur une URL en HTTPS. Les URLs en HTTP simple ne sont pas acceptées pour des raisons de sécurité.
- Au moins un signal configuré. Les webhooks délivrent les signaux que vous avez activés dans votre configuration. Sans signal actif, vous ne recevrez rien.
- Un outil pour tester des requêtes HTTP. cURL, Postman ou tout client HTTP de votre choix.
- Notions de base en HTTP et JSON. Vous devez comprendre ce qu’est une requête POST, un header et un corps JSON.
Étape 1 : Créer votre endpoint de réception
Votre endpoint est un serveur web qui accepte des requêtes POST et répond avec un code HTTP 200. Voici un exemple minimal avec Express.js (Node.js) :
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/rodz', (req, res) => {
const payload = req.body;
console.log('Signal reçu :', payload.signal_type);
console.log('Entreprise :', payload.company.name);
console.log('Timestamp :', payload.timestamp);
// Traitez le signal ici :
// - enregistrement en base de données
// - notification Slack
// - création d'une tâche dans votre CRM
// - déclenchement d'une séquence de prospection
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log('Webhook endpoint actif sur le port 3000');
});Quelques points importants sur votre endpoint :
- Répondez rapidement. Votre endpoint doit renvoyer un code 200 en moins de 10 secondes. Si le traitement du signal prend du temps (appel CRM, enrichissement de données), placez-le dans une file d’attente et répondez immédiatement.
- Acceptez le JSON. Le Content-Type de la requête sera
application/json. - Exposez-le en HTTPS. Si vous développez en local, utilisez un outil comme ngrok pour créer un tunnel HTTPS temporaire.
Pour un environnement de production, préférez un serveur hébergé chez un fournisseur cloud (AWS, GCP, OVH, Scaleway) avec un certificat TLS valide.
Étape 2 : Enregistrer votre webhook via l’API
Une fois votre endpoint prêt, enregistrez-le auprès de Rodz. Envoyez une requête POST à /webhooks avec votre URL, la liste des événements que vous souhaitez recevoir et, optionnellement, un secret pour la vérification HMAC.
curl -X POST https://api.rodz.io/webhooks \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"url": "https://votre-serveur.com/webhooks/rodz",
"events": ["signal.new", "signal.updated"],
"secret": "votre_secret_hmac_256"
}'Paramètres de la requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
url | string | Oui | L’URL HTTPS de votre endpoint |
events | string[] | Oui | Les types d’événements à recevoir (signal.new, signal.updated, signal.deleted) |
secret | string | Non | Un secret partagé pour la vérification HMAC-SHA256 de la signature |
Réponse attendue
{
"id": "wh_abc123def456",
"url": "https://votre-serveur.com/webhooks/rodz",
"events": ["signal.new", "signal.updated"],
"active": true,
"created_at": "2026-03-05T10:30:00Z"
}L’API vous renvoie un identifiant unique pour votre webhook. Conservez-le : il vous servira pour vérifier, modifier ou supprimer l’enregistrement.
Le paramètre secret est fortement recommandé. Il permet de vérifier que les requêtes reçues proviennent bien de Rodz et non d’un tiers malveillant. Nous y reviendrons dans la section sécurité.
Étape 3 : Vérifier l’enregistrement de votre webhook
Pour confirmer que votre webhook a bien été enregistré, interrogez l’endpoint GET /webhooks :
curl -X GET https://api.rodz.io/webhooks \
-H "Authorization: Bearer VOTRE_CLE_API"Réponse
{
"webhooks": [
{
"id": "wh_abc123def456",
"url": "https://votre-serveur.com/webhooks/rodz",
"events": ["signal.new", "signal.updated"],
"active": true,
"created_at": "2026-03-05T10:30:00Z",
"last_triggered_at": null
}
]
}Le champ last_triggered_at est null tant qu’aucun événement n’a été envoyé. Il se mettra à jour automatiquement dès la première livraison.
Pour plus de détails sur les endpoints disponibles, les limites de requêtes et la gestion des erreurs, consultez la référence complète de l’API Rodz.
Étape 4 : Déclencher un événement de test
Avant d’attendre un vrai signal, envoyez un événement de test pour vérifier que votre endpoint fonctionne correctement :
curl -X POST https://api.rodz.io/webhooks/wh_abc123def456/test \
-H "Authorization: Bearer VOTRE_CLE_API"Réponse
{
"status": "sent",
"webhook_id": "wh_abc123def456",
"test_event_id": "evt_test_789"
}Votre endpoint devrait recevoir dans les secondes qui suivent un payload de test. Vérifiez vos logs pour confirmer la bonne réception. L’événement de test contient des données fictives mais respecte exactement la même structure qu’un vrai signal.
Étape 5 : Comprendre le payload webhook
Chaque notification webhook contient un payload JSON structuré. Voici un exemple complet pour un signal de type “levée de fonds” :
{
"event_id": "evt_20260305_abc123",
"event_type": "signal.new",
"signal_type": "fundraising",
"timestamp": "2026-03-05T14:22:00Z",
"company": {
"id": "comp_456def",
"name": "TechStartup SAS",
"domain": "techstartup.fr",
"siren": "123456789",
"industry": "SaaS",
"size": "50-200",
"location": {
"city": "Paris",
"country": "FR"
}
},
"contact": {
"id": "cont_789ghi",
"first_name": "Marie",
"last_name": "Dupont",
"title": "CTO",
"email": "marie.dupont@techstartup.fr",
"linkedin_url": "https://linkedin.com/in/mariedupont"
},
"metadata": {
"amount": 5000000,
"currency": "EUR",
"round": "Series A",
"investors": ["VC Fund Alpha", "Business Angels Club"],
"source_url": "https://example.com/article-levee-techstartup"
}
}Description des champs principaux
Champs d’événement
event_id: identifiant unique de la notification. Utilisez-le pour dédupliquer les messages en cas de retry.event_type: le type d’événement webhook (signal.new,signal.updated,signal.deleted).signal_type: le type de signal d’affaires détecté (fundraising,hiring,relocation,leadership_change, etc.).timestamp: la date et l’heure de détection du signal au format ISO 8601.
Objet company
Contient les informations sur l’entreprise concernée : identifiant interne, nom, domaine, SIREN, secteur d’activité, taille et localisation. Ces données correspondent à celles décrites dans l’article sur la production des signaux Rodz.
Objet contact
Le contact associé au signal, quand il est disponible. Peut contenir le nom, le poste, l’email et le profil LinkedIn. Ce champ peut être null si le signal concerne uniquement l’entreprise.
Objet metadata
Les données spécifiques au type de signal. Pour une levée de fonds : montant, devise, tour et investisseurs. Pour un recrutement : intitulé du poste, département, niveau de séniorité. La structure varie selon le signal_type.
Étape 6 : Répondre correctement et comprendre les retries
Votre endpoint doit renvoyer un code HTTP de la famille 2xx (200, 201 ou 204) pour confirmer la bonne réception du webhook. Tout autre code est considéré comme un échec.
Politique de retry
Lorsque votre endpoint renvoie un code non-2xx ou ne répond pas dans les 10 secondes, Rodz applique une politique de retry avec backoff exponentiel :
| Tentative | Délai après l’échec |
|---|---|
| 1re retry | 30 secondes |
| 2e retry | 5 minutes |
| 3e retry | 30 minutes |
Après 3 tentatives échouées (soit 4 envois au total, incluant l’envoi initial), le webhook est marqué comme échoué pour cet événement. L’événement n’est pas perdu : vous pouvez toujours le récupérer via l’API REST classique.
Si votre endpoint échoue de manière répétée sur plusieurs événements consécutifs, Rodz désactive automatiquement le webhook et vous envoie une notification par email. Vous pourrez le réactiver depuis votre tableau de bord une fois le problème résolu.
Bonnes pratiques pour la fiabilité
- Répondez avant de traiter. Enregistrez le payload dans une file d’attente (Redis, RabbitMQ, SQS) et renvoyez 200 immédiatement. Traitez le signal de manière asynchrone.
- Dédupliquez avec
event_id. En cas de retry, vous pouvez recevoir le même événement plusieurs fois. Stockez lesevent_idtraités pour éviter les doublons. - Surveillez vos logs. Mettez en place des alertes si votre endpoint renvoie des erreurs 5xx de manière récurrente.
Sécuriser la réception avec HMAC-SHA256
Si vous avez fourni un secret lors de l’enregistrement de votre webhook, chaque requête envoyée par Rodz inclut un header X-Rodz-Signature contenant une signature HMAC-SHA256 du payload.
Voici comment vérifier cette signature en Node.js :
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const computed = crypto.createHmac('sha256', secret).update(JSON.stringify(payload)).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computed));
}
// Dans votre handler Express
app.post('/webhooks/rodz', (req, res) => {
const signature = req.headers['x-rodz-signature'];
const isValid = verifySignature(req.body, signature, 'votre_secret_hmac_256');
if (!isValid) {
console.error('Signature invalide, requête rejetée');
return res.status(401).json({ error: 'Invalid signature' });
}
// Le signal est authentifié, traitez-le en toute confiance
res.status(200).json({ received: true });
});La vérification HMAC garantit deux choses : que la requête provient bien de Rodz et que le payload n’a pas été modifié en transit. C’est une protection essentielle contre les attaques par injection.
Pour un guide complet sur la sécurisation de vos webhooks, consultez l’article dédié à la vérification HMAC-SHA256.
Cas d’usage concrets
Une fois vos webhooks en place, les possibilités d’automatisation sont nombreuses. Voici quelques exemples courants.
Alimentation CRM en temps réel
Chaque signal reçu crée ou met à jour un enregistrement dans votre CRM. Une levée de fonds ? Le compte est enrichi et une tâche de suivi est assignée au commercial responsable du secteur. Un changement de dirigeant ? Le contact principal est mis à jour automatiquement.
Notification Slack instantanée
Envoyez les signaux pertinents dans un canal Slack dédié. Votre équipe commerciale est alertée en quelques secondes et peut réagir avant la concurrence. Combiné avec le scoring par signaux, vous pouvez filtrer pour ne notifier que les signaux à fort potentiel.
Déclenchement de séquences de prospection
Connectez vos webhooks à un outil d’automatisation (Make, n8n, Zapier) pour déclencher des séquences de prospection personnalisées en fonction du type de signal. Un recrutement dans le département IT ? Envoyez un message ciblé sur votre solution technique. Une expansion géographique ? Proposez un accompagnement adapté.
Questions fréquentes
Combien de webhooks puis-je enregistrer ?
Vous pouvez enregistrer jusqu’à 10 webhooks par compte. Chaque webhook peut écouter un ou plusieurs types d’événements. Si vous avez besoin de plus de 10 endpoints, contactez l’équipe support.
Les webhooks sont-ils comptabilisés dans ma limite d’appels API ?
Non. Les webhooks sont des notifications sortantes envoyées par Rodz. Ils ne consomment pas votre quota d’appels API. En revanche, si vous utilisez l’API REST pour récupérer des détails supplémentaires après réception d’un webhook, ces appels sont comptabilisés normalement.
Que se passe-t-il si mon endpoint est temporairement indisponible ?
Rodz applique 3 retries avec backoff exponentiel (30 secondes, 5 minutes, 30 minutes). Si les 4 tentatives échouent, l’événement est marqué comme non délivré mais reste accessible via l’API REST. Si votre endpoint échoue de manière répétée, le webhook est désactivé automatiquement.
Puis-je filtrer les signaux envoyés par webhook ?
Les webhooks délivrent tous les signaux qui correspondent à votre configuration de signaux active. Pour filtrer plus finement, vous avez deux options : ajuster votre configuration de signaux en amont, ou filtrer côté serveur dans votre endpoint en inspectant le champ signal_type du payload.
Comment tester mes webhooks en local pendant le développement ?
Utilisez un outil de tunneling comme ngrok. Lancez ngrok http 3000 pour obtenir une URL HTTPS publique qui redirige vers votre serveur local. Enregistrez cette URL temporaire comme webhook et utilisez l’endpoint de test pour vérifier le bon fonctionnement.
Le payload contient-il toujours un contact ?
Non. Certains signaux concernent uniquement l’entreprise (déménagement, changement de statut juridique, publication de comptes). Dans ce cas, le champ contact est null. Les signaux liés à des personnes (nomination, recrutement) incluent systématiquement un objet contact.
Comment supprimer un webhook ?
Envoyez une requête DELETE à /webhooks/{webhook_id} :
curl -X DELETE https://api.rodz.io/webhooks/wh_abc123def456 \
-H "Authorization: Bearer VOTRE_CLE_API"Le webhook est immédiatement désactivé et supprimé. Les événements déjà en file d’attente ne seront pas délivrés.
Puis-je recevoir des webhooks pour des signaux passés ?
Non. Les webhooks ne fonctionnent qu’en temps réel, à partir du moment de l’enregistrement. Pour accéder aux signaux historiques, utilisez l’API REST avec les filtres de date. L’article de référence API détaille les paramètres disponibles.
Prochaines étapes
Vos webhooks sont configurés et fonctionnels. Voici comment aller plus loin :
- Sécurisez vos endpoints en implémentant la vérification HMAC-SHA256 complète. Consultez le guide de sécurisation des webhooks.
- Explorez la référence API pour découvrir tous les endpoints, les limites de requêtes et la gestion des erreurs : référence complète de l’API Rodz.
- Consultez la documentation interactive sur api.rodz.io/docs pour tester les endpoints directement depuis votre navigateur.
Les webhooks sont le socle de toute intégration temps réel avec Rodz. En les combinant avec une configuration de signaux bien pensée et un traitement asynchrone robuste, vous construisez un pipeline de prospection qui réagit en quelques secondes aux événements de marché.