Webhooks d'événements sortants

Cette page explique les webhooks d'événements sortants : Almirant envoie des notifications d'événements de projet à votre serveur. Pour démarrer un agent depuis un système externe, utilisez les webhooks d'agents.

Almirant envoie des notifications HTTP sortantes à votre serveur lorsque des événements se produisent dans vos projets. Chaque fois qu'un work item est créé, déplacé entre des colonnes ou qu'un sprint est fermé, Almirant envoie une requête POST à l'URL que vous configurez.

Cela est utile pour :

• Synchroniser Almirant avec des outils externes (Slack, Discord, votre propre tableau de bord)
• Déclencher des pipelines CI/CD lorsqu'une tâche change d'état
• Alimenter des systèmes d'analytique ou de reporting
• Automatiser des flux personnalisés en dehors d'Almirant

Créer un webhook

1. Accédez à Configuration > Webhooks dans votre projet
2. Cliquez sur Créer un webhook
3. Remplissez les champs :

Champ	Description	Exemple
URL	Point de terminaison HTTPS qui recevra les notifications	https://mi-servidor.com/webhooks/almirant
Événements	Types d'événements qui déclenchent le webhook	work_item.created, sprint.closed
Secret	Clé secrète pour valider l'authenticité des requêtes	Il est généré automatiquement ou vous pouvez définir le vôtre

4. Cliquez sur Enregistrer

Important

L'URL doit être accessible depuis Internet et utiliser HTTPS. Almirant n'enverra pas de webhooks vers des URL HTTP non chiffrées (à l'exception de localhost en développement).

Événements disponibles

Sélectionnez un ou plusieurs événements lors de la création du webhook :

Événement	Se déclenche lorsque...
work_item.created	Un nouveau work item est créé
work_item.updated	Des champs d'un work item sont modifiés (titre, description, priorité, etc.)
work_item.moved	Un work item est déplacé entre les colonnes du board
work_item.archived	Un work item est archivé
lead.created	Un nouveau lead est créé dans le CRM
lead.updated	Les données d'un lead sont mises à jour
lead.stage_changed	Un lead change d'étape dans le funnel
sprint.created	Un nouveau sprint est créé
sprint.closed	Un sprint est fermé

Conseil

Si vous devez uniquement réagir aux changements du tableau, sélectionnez seulement les événements work_item.*. Moins vous vous abonnez à des événements, moins votre serveur recevra de trafic.

Vérifier la signature du webhook

Chaque requête inclut une signature HMAC-SHA256 dans l'en-tête X-Almirant-Signature, qui permet de vérifier que la requête provient réellement d'Almirant et n'a pas été manipulée.

Fonctionnement de la vérification

1. Almirant génère un hachage HMAC-SHA256 du corps de la requête en utilisant votre secret comme clé
2. Il inclut le hachage dans l'en-tête X-Almirant-Signature
3. Votre serveur recalcule le hachage avec le même secret et compare

Exemple en Node.js

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Dans votre point de terminaison :
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // Corps sous forme de chaîne, non analysé

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Firma invalida' });
  }

  const event = JSON.parse(rawBody);
  console.log('Evento recibido:', event.type);

  // Traiter l'événement...

  res.status(200).json({ received: true });
});

Exemple en Python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Sécurité

Vérifiez toujours la signature avant de traiter l'événement. Ne faites jamais confiance aux données du webhook sans valider leur authenticité. Utilisez timingSafeEqual (ou l'équivalent) pour éviter les attaques temporelles.

Consulter les logs de livraison

Chaque webhook conserve un historique des livraisons que vous pouvez consulter pour déboguer les problèmes.

1. Accédez à Configuration > Webhooks
2. Cliquez sur le webhook que vous souhaitez inspecter
3. Dans l'onglet Livraisons, vous verrez une liste avec :

Colonne	Description
Date	Moment exact de la livraison
Événement	Type d'événement qui a déclenché la livraison
État	Code de réponse HTTP (200, 500, timeout, etc.)
Durée	Temps de réponse de votre serveur

Cliquez sur n'importe quelle livraison pour voir le détail complet : en-têtes envoyés, corps de la charge utile et réponse de votre serveur.

Nouvelles tentatives et échecs

Almirant relance automatiquement les livraisons ayant échoué avec un délai d'attente exponentiel :

Tentative	Attente avant la nouvelle tentative
1	Immédiat
2	1 minute
3	5 minutes
4	30 minutes
5	2 heures

Un échec est considéré comme tel lorsque :

• Votre serveur répond avec un code HTTP >= 400
• Votre serveur ne répond pas dans les 10 secondes (délai d'expiration)
• Impossible d'établir une connexion avec votre serveur

Après 5 tentatives échouées, la livraison est marquée comme échouée et n'est plus relancée. Vous pouvez la renvoyer manuellement depuis le log des livraisons.

Note

Votre serveur doit répondre avec un code HTTP 2xx (idéalement 200) aussi rapidement que possible. Si vous devez effectuer un traitement long, acceptez immédiatement le webhook et traitez les données de manière asynchrone.

Désactiver ou supprimer un webhook

• Désactiver : Dans la liste des webhooks, utilisez l'interrupteur pour désactiver temporairement. Les livraisons sont suspendues, mais la configuration est conservée.
• Supprimer : Cliquez sur l'icône de suppression. Cette action est irréversible et supprime également l'historique des livraisons.