osFoundry / Platform
Webhooks entrants
Une URL par application ou espace de travail pour recevoir des événements. Vérification de signature incluse.
Présentation
Les webhooks entrants donnent à osFoundry une adresse de réception ouverte sur le monde extérieur. Vous générez un jeton limité à une app, une instance et un canal précis, et osFoundry vous renvoie une URL dédiée sous /api/v1/webhooks/inbound/{id}. Les systèmes externes (Stripe, GitHub, Zapier, un pipeline CI, votre propre backend) envoient du JSON en POST vers cette URL, et l'événement arrive dans le canal temps réel que vous avez choisi, où votre chat, vos agents et vos apps peuvent agir dessus. Pas de polling, pas de serveur d'intégration séparé à faire tourner : le point de terminaison est l'intégration.\n\nLa vérification de signature est intégrée, pas rajoutée par-dessus. Chaque jeton porte un secret de signature HMAC-SHA256, affiché une seule fois au moment de la génération. L'émetteur calcule une signature sur la charge utile et la transmet dans l'en-tête X-OsFoundry-Signature ; osFoundry la valide à chaque requête et rejette tout ce qui n'est pas signé ou a été altéré en transit. Lorsque vous devez changer la clé d'un émetteur, faire tourner le secret ouvre une fenêtre de tolérance de 7 jours pendant laquelle le secret précédent reste valide, de sorte que la rotation ne perd jamais un événement en cours. Révoquer un jeton est immédiat : le point de terminaison se met à renvoyer 401 sur-le-champ, ce qui est la voie rapide face à un secret divulgué ou à une intégration mise hors service.\n\nComme tout cela s'exécute dans l'espace de travail bureau BYOK d'osFoundry, un événement entrant peut déclencher les mêmes agents, apps et connaissances avec lesquels vous travaillez déjà, sans taxe d'intégration par siège ni détour de vos données par un intermédiaire tiers. Chaque jeton enregistre son heure de dernière utilisation et son nombre de requêtes sur 24 heures, pour que vous voyiez quels émetteurs sont actifs, et la plateforme conserve les 100 dernières requêtes entrantes en vue d'un rejeu, ce qui transforme le débogage des webhooks : au lieu de deviner, vous rejouez la charge utile réelle.
Fonctionnalités clés
- Générez une URL de réception dédiée par app, instance et canal : les systèmes externes envoient les événements JSON en POST directement vers ce point de terminaison sous /api/v1/webhooks/inbound/{id}
- Chaque requête est vérifiée contre une signature HMAC-SHA256 dans l'en-tête X-OsFoundry-Signature, si bien que les charges utiles non signées ou falsifiées sont rejetées avant d'atteindre votre canal
- Faites tourner un secret de signature avec une fenêtre de tolérance de 7 jours pendant laquelle l'ancien secret valide encore, pour changer la clé des émetteurs sans perdre d'événements
- Révoquez un jeton sur-le-champ : le point de terminaison renvoie 401 dès la révocation, coupant un émetteur divulgué ou retiré
- Consultez l'heure de dernière utilisation et le nombre de requêtes sur 24 heures par jeton, et rejouez les 100 dernières requêtes entrantes depuis les réglages du déclencheur quand vous devez déboguer une livraison
Cas d’usage
- Développeur branchant Stripe : il génère un jeton limité à un canal de facturation, pointe le webhook de Stripe vers l'URL, et laisse osFoundry rejeter tout POST dont la signature HMAC ne correspond pas avant qu'il n'atteigne un agent
- Ingénieur ops face à un secret divulgué : il révoque le jeton concerné pour un 401 immédiat et en génère un neuf, sans mettre à terre les autres intégrations qui alimentent l'espace de travail
- Créateur d'automatisations reliant un pipeline CI : il envoie les événements de statut de build en POST vers un canal où un agent trie les échecs, en s'appuyant sur le rejeu des 100 dernières requêtes pour déboguer la forme de la charge utile
Questions fréquentes
Comment osFoundry vérifie-t-il qu'un webhook entrant est authentique ?
Chaque jeton entrant possède un secret de signature HMAC-SHA256. L'émetteur calcule une signature sur le corps de la requête et l'envoie dans l'en-tête X-OsFoundry-Signature, et osFoundry la recalcule et la compare à chaque requête. Les requêtes dont la signature est absente ou invalide sont rejetées, si bien que seul un système détenant le secret peut publier dans votre canal. Le secret est affiché une seule fois à la génération : conservez-le à ce moment-là, car il n'est plus renvoyé ensuite.
Qu'advient-il des événements en cours quand je fais tourner ou révoque un jeton ?
La rotation vous offre une fenêtre de tolérance de 7 jours pendant laquelle le nouveau et l'ancien secret valident tous deux, de sorte que vous pouvez mettre à jour chaque émetteur sans perdre d'événements pendant la bascule. La révocation est l'inverse, par conception : le point de terminaison renvoie 401 immédiatement et coupe l'émetteur sur-le-champ, ce que vous voulez précisément si un secret fuit ou si une intégration est retirée.
Ai-je une seule URL de webhook pour tout, ou puis-je les cloisonner ?
Chaque jeton est limité à une app, une instance et un canal précis, et génère sa propre URL sous /api/v1/webhooks/inbound/{id}. Cela signifie qu'un émetteur ne peut pas publier dans un canal auquel il n'a pas été autorisé, et que vous pouvez révoquer ou faire tourner une seule intégration sans toucher aux autres. Chaque jeton indique aussi son heure de dernière utilisation et son nombre de requêtes sur 24 heures, pour que vous sachiez quels points de terminaison reçoivent réellement du trafic.