Webhooks – iceScrum

Documentation Cette documentation ne s'applique qu'à iceScrum v7.
Pour un vieux serveur iceScrum R6, lisez la documentation correspondante ou migrez.

Contents


Les Webhooks permettent aux services externes d’être automatiquement avertis par une requête HTTP lorsque des événements importants se produisent dans iceScrum.

Principes

Les Webhooks vous permettent d’intégrer iceScrum avec des applications web tierces en leur permettant de s’abonner aux événements iceScrum. Lorsqu’un de ces événements est déclenché, une requête HTTP POST contenant un payload JSON est envoyée à l’URL configurée.

Les Webhooks vous permettent de créer des intégrations élaborées et de personnaliser votre expérience iceScrum. Vous pouvez les utiliser en combinaison avec l’API REST d’iceScrum. L’utilisation de Webhooks est une bonne alternative au « polling » régulier de données, obtenant le même résultat avec une utilisation moindre des ressources tout en nécessitant moins de travail de votre part.

Créer un Webhook

Pour créer un Webhook sur votre projet, activez l’App correspondante. Ouvrez ensuite les paramètres de votre projet dans la section « Webhooks » en étant connecté en tant que Product Owner ou ScrumMaster.

Définissez alors votre Webhook :

  • URL du Webhook : cette URL recevra vos données lorsque des événements iceScrum se produisent. Attention, cela peut entraîner une fuite de données si cette URL n’est pas sécurisée.
  • Clé secrète (facultatif) : lorsqu’elle est définie, cette clé est utilisée pour générer une signature qui permettra au destinataire de valider le payload.
  • Vérification SSL : par défaut, le certificat SSL de l’URL Webhook est vérifié lors de l’envoi de la requête. Ne désactivez la vérification que si vous savez ce que vous faites !
  • Événements : soit les événements de l’histoire, tous les événements (histoires, tâches, caractéristiques, tests d’acceptation, sprints, commentaires…) ou des événements sélectionnés.
  • Activer : les événements sont envoyés à l’URL du Webhook uniquement si le Webhook est activé.

HTTP request

La requête HTTP POST générée pour l’événement contient des en-têtes HTTP et un payload.

Le payload contient la totalité de l’objet JSON associé à l’événement, par exemple la story, comme vous l’obtiendriez par l’API REST correspondante.

En plus du payload, la requête contient des en-têtes HTTP spécifiques :

  • x-icescrum-event : code qui identifie le type d’événement, par ex. story.create, story.update…
  • x-icescrum-signature : fourni uniquement si une clé secrète a été configurée. C’est le HMAC de l’évènement. C’est le résultat de la fonction sha1 appliquée à votre clé secrète et au payload. Si le destinataire connaît la clé secrète, il peut générer sa propre signature à partir de la clé et du payload reçu afin de la comparer à la signature fournie dans cet en-tête. Ceci permet de vérifier que le contenu n’a pas été altéré.

Si les requêtes HTTP échouent 5 fois de suite (la limite peut être modifiée dans l’administration du serveur), le Webhook est automatiquement désactivé afin d’éviter de générer trop d’erreurs.

Liste des Webhooks

Vous pouvez définir autant de Webhooks que nécessaire, et mettre à jour ou supprimer des Webhooks à tout moment.

Le formulaire « Nouveau Webhook » n’est pas le seul moyen de créer des hooks. En effet, ils peuvent être créés via notre API REST ou via l’utilisation d’autres Apps (par ex. Zapier). Selon leur provenance, vous pouvez ou non avoir la possibilité de les mettre à jour manuellement.

Previous << Agile KPIs
Next Forecast >>

Essayez gratuitement dès maintenant
Tout ce dont vous avez besoin pour gérer vos projets agiles