Source Webhook
En bref
La source Webhook permet a un systeme externe d'envoyer des donnees en temps reel a la plateforme. Contrairement a la source HTTP ou la plateforme interroge periodiquement une API, le webhook fonctionne en mode push : c'est le systeme externe qui notifie la plateforme a chaque nouvel evenement.
Avant de commencer
- Acces a un workspace avec le module Live Data
- Un systeme externe capable d'envoyer des requetes HTTP (Stripe, GitHub, HubSpot, n8n, etc.)
Comment ca marche
- Vous creez une source webhook dans Ontologie et obtenez une URL de reception unique.
- Votre systeme externe envoie des requetes HTTP vers cette URL.
- Ontologie valide la requete (signature HMAC, API key, etc.) et ingere les donnees.
- Les donnees sont mappees vers les proprietes de l'entite cible dans votre ontologie.
Assistant de configuration (3 etapes)
Depuis le catalogue Live Data, cliquez sur Configurer sur la carte Webhook (section Sources Directes). L'assistant se deroule en 3 etapes.
Etape 1 — Configuration
Definissez les parametres de base du webhook :
| Champ | Description | Obligatoire |
|---|---|---|
| Nom du webhook | Nom explicite de la source (ex. Stripe Events, HubSpot Contacts) | Oui |
| Description | Description libre de l'usage du webhook | Non |
| Methode HTTP attendue | Methode acceptee pour les requetes entrantes : POST (defaut), GET, PUT, PATCH ou DELETE | Oui |
Authentification
Choisissez le mode de securisation des requetes entrantes :
| Mode | Configuration |
|---|---|
| Aucune | Pas de verification (deconseille en production) |
| API Key (header) | Nom du header (ex. X-API-Key) et valeur secrete. Un bouton permet de generer automatiquement une valeur aleatoire. |
| Basic | Identifiant et mot de passe. Un bouton permet de generer automatiquement un mot de passe. |
| JWT | Algorithme (HS256 ou RS256) et secret ou cle publique selon l'algorithme choisi. |
Signature HMAC (optionnel)
En complement de l'authentification, vous pouvez activer la validation HMAC-SHA256. Renseignez un secret partage (un bouton genere un secret de 32 caracteres). Ontologie verifiera la signature transmise dans le header X-Webhook-Signature a chaque requete.
Cliquez sur Suivant pour passer a l'etape 2.
Etape 2 — Mapping
Configurez le lien entre les champs du payload JSON et les proprietes d'une entite de votre ontologie.
Panneau gauche — Payload JSON :
Collez un exemple de payload JSON que votre systeme externe enverra. Ontologie detecte automatiquement les champs disponibles et les affiche sous forme de badges. Si le JSON est invalide, un message d'erreur apparait.
Panneau droit — Entite et correspondances :
- Selectionnez une entite cible en la recherchant par nom ou description dans la liste.
- Configurez les correspondances entre les champs detectes et les proprietes de l'entite :
- Le bouton Auto propose des correspondances automatiques basees sur la similarite des noms de champs.
- Le bouton Ajouter permet d'ajouter manuellement une correspondance.
- Chaque ligne de mapping associe un champ source (du payload) a un champ cible (propriete de l'entite).
Cliquez sur Suivant pour passer a l'etape 3.
Etape 3 — Validation
Testez la reception en conditions reelles avant d'activer la source.
Panneau gauche — Capture en direct :
L'assistant affiche l'URL de reception du webhook (temporaire en mode creation) avec la methode HTTP configuree. Vous pouvez la copier pour la configurer dans votre systeme externe.
- Cliquez sur Demarrer la capture pour ouvrir une session d'ecoute de 3 minutes.
- Envoyez une requete depuis votre systeme externe vers l'URL affichee.
- Lorsque la requete est recue, l'assistant affiche le payload capture.
Un indicateur de connexion WebSocket (vert = connecte, rouge = deconnecte) confirme que l'ecoute est active.
Panneau droit — Apercu du payload :
Une fois la requete capturee, le panneau affiche :
- Le payload JSON brut recu
- Un tableau de correspondance montrant les valeurs resolues pour chaque mapping configure a l'etape 2
Actions finales :
| Action | Description |
|---|---|
| Creer et activer | Cree la source et l'active immediatement (necessite une capture reussie) |
| Creer sans test | Cree la source sans tester la reception (utile si le systeme externe n'est pas encore configure) |
Liaison a une entite de l'ontologie
Lorsque vous creez un webhook depuis l'onglet Sources d'une entite dans l'ontologie, la liaison est automatique : les donnees recues sont directement associees a cette entite.
Comment ca marche
- Ouvrez une entite dans l'ontologie et cliquez sur l'onglet Sources.
- Dans la section Connecteurs Directs, selectionnez l'onglet Webhook puis cliquez sur Creer Webhook.
- Le webhook cree est automatiquement lie a l'entite courante.
- A chaque requete recue, les donnees sont enrichies avec la reference a l'entite et les correspondances configurees a l'etape 2 du wizard sont appliquees.
Depuis le catalogue Live Data
Si vous creez un webhook depuis le catalogue Live Data (et non depuis l'entite), vous pouvez lier manuellement le webhook a une entite via l'etape 2 du wizard (Mapping → selection de l'entite cible).
Creer un webhook directement depuis l'onglet Sources d'une entite est le moyen le plus simple : la liaison est automatique et le contexte de l'entite est pre-rempli.
→ En savoir plus : Liaison aux entites
Format des requetes
La plateforme attend des requetes au format JSON :
POST /reference/api/webhooks/{endpointId}
Content-Type: application/json
X-Webhook-Signature: sha256=... (si HMAC active)
Le corps de la requete doit etre un objet JSON valide. Ontologie traite le payload et l'associe a la source identifiee par endpointId.
Securite
| Mecanisme | Description |
|---|---|
| Authentification | Verification de l'identite de l'appelant (API Key, Basic, JWT) |
| Signature HMAC-SHA256 | Verification de l'integrite du payload via un secret partage |
| Rejet automatique | Les requetes non conformes sont rejetees avec un code d'erreur |
Ne partagez jamais les secrets webhook dans du code source, des logs ou des documents partages. Utilisez des variables d'environnement pour les stocker cote systeme externe.
Resultat attendu
Les evenements de votre systeme externe arrivent en temps reel dans la plateforme. Les donnees sont automatiquement mappees vers les proprietes de l'entite cible et consultables dans le detail de la source.
Limites
| Limite | Valeur |
|---|---|
| Taille payload | 1 Mo maximum |
| Timeout de traitement | 30 secondes |
| Duree de capture | 3 minutes (extensible de 2 minutes) |
| Requetes simultanees | Rate limite par workspace |
Voir aussi
- Source HTTP — Interrogation periodique d'une API externe (mode pull)
- Monitoring — Suivre vos synchronisations
- Diagnostic — Resoudre les erreurs de reception
- Support et contact