Webhooks
En bref
Les webhooks permettent a un systeme externe d'envoyer des evenements en temps reel a Ontologie. Contrairement aux sources REST ou Ontologie interroge periodiquement une API, les webhooks fonctionnent en mode push : c'est le systeme externe qui notifie Ontologie a chaque nouvel evenement.
Avant de commencer
- Un connecteur de type webhook cree (voir Ajouter un connecteur)
- Un systeme externe capable d'envoyer des requetes HTTP POST
- Un secret partage pour la validation HMAC
Comment ca marche
Le flux de reception d'un webhook se deroule en 4 etapes :
- Votre systeme externe envoie une requete HTTP POST vers l'URL de reception Ontologie.
- Ontologie valide la signature HMAC-SHA256 incluse dans les headers de la requete.
- Si la signature est valide, les donnees sont ingerees dans votre workspace.
- Les donnees sont disponibles et peuvent etre liees a vos entites d'ontologie.
Etapes
1. Creez un connecteur webhook
Depuis Live Data, creez un connecteur de type Webhook (voir Ajouter un connecteur).
2. Notez l'URL de reception
Apres creation, Ontologie genere une URL de reception unique. C'est l'adresse a configurer dans votre systeme externe pour envoyer les evenements.
3. Configurez le secret de validation
Renseignez un secret partage entre Ontologie et votre systeme externe. Ontologie utilise ce secret pour verifier que les evenements proviennent bien de votre systeme.
4. Configurez votre systeme externe
Dans votre systeme externe (Stripe, GitHub, etc.), configurez l'envoi de webhooks vers l'URL fournie par Ontologie. Renseignez le meme secret pour que la signature soit correctement generee.
5. Testez la reception
Declenchez un evenement depuis votre systeme externe et verifiez sa reception dans Ontologie. Le connecteur affiche les evenements recus avec leur statut.
Format des evenements
Ontologie attend des requetes au format JSON avec un header de signature :
POST /api/webhooks/{endpointId}
Content-Type: application/json
X-Webhook-Signature: sha256=...
Le corps de la requete doit etre un objet JSON valide. Ontologie traite le payload et l'associe au connecteur identifie par endpointId.
Securite
La securite des webhooks repose sur la validation cryptographique de chaque requete :
- Validation HMAC-SHA256 : chaque requete entrante est verifiee a l'aide du secret partage.
- Rejet automatique : les requetes sans signature valide sont rejetees avec un code d'erreur.
- Replay protection : les requetes sont horodatees pour eviter les rejeux.
Ne partagez jamais le secret webhook dans du code source, des logs ou des documents partages. Utilisez des variables d'environnement pour le stocker cote systeme externe.
Resultat attendu
Les evenements de votre systeme externe arrivent en temps reel dans Ontologie. Vous pouvez les consulter dans le detail du connecteur et les lier a vos entites d'ontologie.
Limites
| Limite | Valeur |
|---|---|
| Taille payload | 1 Mo maximum |
| Timeout de traitement | 30 secondes |
| Requetes simultanees | Rate limite par workspace |
Besoin d'aide ?
Consultez la page Monitoring pour suivre vos synchronisations, la page Diagnostic pour resoudre les erreurs de reception, la page Catalogue de connecteurs pour la creation initiale, ou ecrivez-nous : Support et contact.