Webhooks Orbit

Les webhooks envoient un HTTP POST signé à une URL de votre choix chaque fois qu'un déploiement change d'état, de sorte que votre équipe entend parler d'une compilation échouée dans le canal qu'elle regarde déjà au lieu de l'apprendre d'un client.

Où se trouvent les webhooks

Ouvrez Orbit, cliquez sur le projet et choisissez Webhooks sous le groupe Configure dans la bande d'onglets du projet. La page s'intitule Webhooks et se décrit comme recevant des notifications HTTP POST lorsque les déploiements changent d'état, avec Slack, Discord et JSON générique supportés.

Ajouter un webhook

1. Dans la carte Add a webhook, donnez-lui un Label. Quelque chose comme la destination vers laquelle il envoie.
2. Collez l'URL. Elle doit commencer par https://.
3. Sous Trigger on, cochez les événements que vous voulez.
4. Cliquez sur Add webhook.

Le secret de signature est affiché une fois, immédiatement après la création, avec un avertissement qu'il ne sera pas affiché à nouveau. Copiez-le avant de naviguer ailleurs.

Un projet peut contenir jusqu'à dix webhooks. L'ajout d'un onzième est refusé avec un message nommant la limite.

Les cinq événements

Choisissez délibérément. S'abonner à tous les cinq sur un projet actif transforme un canal d'alerte utile en bruit que tout le monde désactive. Pour la plupart des équipes, Failed seul est le bon point de départ, avec Succeeded ajouté seulement où une notification de déploiement est vraiment utile, comme un canal de production.

Slack et Discord

Si l'URL est un webhook entrant Slack ou un webhook Discord, Orbit le détecte à partir de l'URL et envoie un message formaté plutôt que du JSON brut. La page l'indique sous le champ URL : les URL Slack et Discord sont détectées automatiquement.

Le message formaté porte le nom du projet, l'événement, la branche, le commit court, le temps de compilation, l'URL déployée et le texte d'erreur en cas d'échec. La couleur suit l'événement, de sorte qu'une carte rouge dans le canal signifie un échec sans que personne ne la lise.

Rien d'autre n'est nécessaire. Créez le webhook entrant dans Slack ou Discord, collez l'URL ici, choisissez vos événements, et vous avez terminé.

Payloads JSON génériques

Toute autre URL reçoit un corps JSON. Les champs sont :

Utilisez deliveryId pour rendre votre endpoint idempotent. Si vous relancez une livraison ou qu'une défaillance réseau cause un doublon, l'id vous permet de reconnaître que vous l'avez déjà traité.

Vérifier la signature

Chaque livraison porte trois en-têtes :

• X-Orbit-Signature-256, un HMAC-SHA256 du corps de la requête exact en utilisant votre secret de signature, formaté comme sha256= suivi du digest hex.
• X-Orbit-Event, le nom de l'événement.
• X-Orbit-Delivery, l'id de livraison.

Vérifiez la signature avant d'agir sur une payload. Calculez le même HMAC sur les octets du corps brut et comparez en utilisant une comparaison en temps constant plutôt que l'égalité de chaîne.

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).end();
}

Tester un webhook

Chaque ligne de webhook a Send test delivery. Elle envoie une vraie livraison à votre endpoint immédiatement et rapporte le code HTTP qu'elle a reçu, ou le détail de l'échec.

Utilisez-le immédiatement après l'ajout d'un webhook, avant de le mettre en production. Une règle de pare-feu ou une route qui accepte uniquement GET est beaucoup plus facile à trouver maintenant que pendant un incident.

Historique de livraison

Chaque ligne porte une sparkbar des sept derniers jours avec le nombre de livraisons, le pourcentage de succès et la durée moyenne, plus l'heure et le résultat de la dernière livraison.

Développez Show delivery history pour les livraisons individuelles : l'événement, le code de réponse, la durée et le texte d'erreur s'il y en avait un. Toute livraison peut être renvoyée avec Retry delivery, qui rapporte le code qu'elle a reçu.

Les livraisons expirent après douze secondes. Si votre endpoint fait un travail lent, accusez réception avec un 200 d'abord et traitez ensuite, plutôt que de garder la connexion ouverte.

Rotation du secret

Cliquez sur Rotate secret. Le nouveau secret est affiché une fois, et l'infobulle indique explicitement que l'ancien secret devient invalide immédiatement.

Cela signifie qu'il y a une courte fenêtre où les livraisons sont signées avec un secret que votre endpoint ne connaît pas. Prévoyez-la : effectuez la rotation à un moment calme et mettez à jour votre endpoint comme prochaine action.

Effectuez une rotation quand quelqu'un ayant accès au secret s'en va, ou s'il a jamais été collé dans un canal partagé ou un ticket.

Désactiver et supprimer

Disable webhook arrête les livraisons mais conserve la configuration et l'historique, et la ligne affiche un badge Disabled. C'est le bon choix lorsque vous pausez les alertes, par exemple lors d'une migration planifiée qui produira beaucoup de bruit.

Delete webhook le supprime entièrement. Utilisez disable sauf si vous en êtes sûr.

Autres façons d'être averti

Les webhooks sont l'option flexible. Deux alternatives plus légères se trouvent dans Settings :

• Deploy email notifications, avec trois paramètres : tous les déploiements, les échecs uniquement ou désactivé.
• Notification channels, qui envoient à une URL de webhook en cas de succès ou d'échec de déploiement, régressions de compilation et régressions de bundle, avec leur propre historique de livraison et bouton de test.

Voir Orbit Project Settings pour les deux.

Dépannage

Les livraisons s'affichent comme échouées avec un code HTTP. Votre endpoint a retourné une erreur. Le code vous dit laquelle : 404 signifie que le chemin est mauvais, 401 ou 403 signifie généralement que votre propre vérification de signature le rejette, et 500 signifie que votre handler a levé une exception.

Les livraisons échouent avec un timeout. Votre endpoint a pris plus de douze secondes. Retournez 200 immédiatement et faites le travail de manière asynchrone.

Rien n'est livré du tout. Vérifiez que le webhook est activé et que l'événement attendu est coché. Une compilation qui n'est jamais mise en file d'attente ne déclenche pas d'événement en attente.

La signature ne valide jamais. Presque toujours le problème du corps brut décrit ci-dessus. Enregistrez les octets exacts que vous hashez et comparez leur longueur avec l'en-tête Content-Length.

Une URL Slack reçoit du JSON brut. Les webhooks entrants Slack se trouvent sous hooks.slack.com. Une URL Slack différente ne sera pas détectée comme une.

Où aller ensuite

• Triggering Deployments Via Deploy Hooks pour la direction entrante.
• Orbit Project Settings pour les notifications par email et les canaux de notification.
• Orbit Status Page pour informer vos clients, pas seulement votre équipe.