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) |
Format des requetes
La plateforme attend des requetes au format JSON :
POST /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