Webhooks

Qu'est-ce qu'un webhook ?

Un webhook est une requête HTTP POST que Saasy envoie automatiquement vers l'URL de ton choix chaque fois qu'un événement se produit sur ton board. Contrairement au polling — où tu dois interroger l'API à intervalles réguliers — les webhooks te poussent l'information au moment exact où elle est disponible.

C'est le moyen le plus efficace d'intégrer Saasy à ton infrastructure : ton serveur reçoit la donnée en temps réel et peut réagir immédiatement (notifier une équipe, mettre à jour une base de données, déclencher un workflow, etc.).

Créer un webhook

1. Dans ton tableau de bord, va dans Paramètres > Webhooks.
2. Clique sur Ajouter un webhook.
3. Saisis l'URL de ton endpoint (elle doit être accessible depuis Internet et répondre sur HTTPS).
4. Sélectionne les événements que tu veux recevoir.
5. Clique sur Enregistrer.

Tu peux créer plusieurs webhooks pour le même board, chacun avec sa propre URL et sa propre sélection d'événements.

Événements disponibles

Vérifier la signature

Chaque requête envoyée par Saasy inclut un en-tête X-Saasy-Signature contenant une signature HMAC-SHA256 calculée à partir du corps brut de la requête et de ton secret webhook. Tu dois toujours vérifier cette signature avant de traiter le payload, afin de t'assurer que la requête provient bien de Saasy et non d'une source tierce.

Voici comment verifier la signature selon ton langage serveur :

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Dans ton handler Express
app.post('/webhooks/saasy', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-saasy-signature'];
  if (!verifySignature(req.body, signature, process.env.SAASY_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Traiter l'evenement...
  res.status(200).send('OK');
});

• payload : le corps brut de la requete HTTP (Buffer ou string), avant tout parsing JSON.
• signature : la valeur de l'en-tete X-Saasy-Signature.
• secret : le secret genere par Saasy lors de la creation du webhook (visible dans Parametres > Webhooks).

Exemple de payload

Voici le format d'un payload pour l'événement idea.created :

{
  "event": "idea.created",
  "timestamp": "2024-11-15T10:32:00.000Z",
  "boardId": "brd_01hx9k2m3n4p5q6r7s8t",
  "data": {
    "id": "idea_01hx9k2m3n4p5q6r7s8u",
    "title": "Mode sombre pour le tableau de bord",
    "description": "Ce serait top d'avoir un mode sombre natif sur toutes les pages.",
    "status": "open",
    "votes": 0,
    "authorId": "usr_01hx9k2m3n4p5q6r7s8v",
    "createdAt": "2024-11-15T10:32:00.000Z"
  }
}

Tous les payloads partagent la même structure de base : event, timestamp, boardId et data. Le contenu de data varie selon l'événement.

Politique de relance

Si ton endpoint ne répond pas avec un code HTTP 2xx, Saasy relance automatiquement la requête selon la stratégie suivante :

• 3 tentatives au total avec un backoff exponentiel (attente croissante entre chaque essai).
• Désactivation automatique après 10 échecs consécutifs : le webhook passe en statut disabled pour éviter de surcharger ton serveur.
• Vérification quotidienne : chaque jour, Saasy envoie un événement test.ping aux endpoints désactivés. Si ton serveur répond avec succès, le webhook est automatiquement réactivé.

Tu peux aussi consulter l'historique des livraisons et rejouer manuellement n'importe quel événement depuis Paramètres > Webhooks > Historique.