Webhooks

Les webhooks sortants vous permettent de recevoir des notifications HTTP POST en temps réel lorsque des événements se produisent dans votre projet.

Présentation

Les webhooks livrent un payload JSON à n’importe quel endpoint HTTPS que vous configurez chaque fois qu’un événement spécifique se produit dans votre projet. Chaque webhook peut s’abonner à un ou plusieurs des événements suivants :

Les webhooks sont définis par projet individuel. Chaque projet dispose de son propre ensemble d’endpoints de webhooks avec des configurations et des secrets de signature indépendants.

Configurer un webhook

1. Accédez à la page Intégrations de votre projet
2. Faites défiler jusqu’à la section Webhooks sortants
3. Cliquez sur Ajouter un webhook
4. Entrez l’URL de votre endpoint (doit être HTTPS en production)
5. Sélectionnez les événements auxquels vous souhaitez vous abonner
6. Cliquez sur Enregistrer

Après l’enregistrement, un secret de signature est affiché une seule fois. Copiez-le immédiatement — il ne peut pas être récupéré ultérieurement. Vous pouvez le régénérer à tout moment depuis le menu d’actions du webhook.

Vérifier les signatures des webhooks

Chaque livraison de webhook inclut un header X-SupDesk-Signature contenant une signature HMAC-SHA256 du corps de la requête. Pour vérifier un webhook :

1. Calculez HMAC-SHA256(votre_secret_de_signature, corps_brut_de_la_requête)
2. Comparez le résultat avec la valeur hexadécimale dans le header X-SupDesk-Signature (après le préfixe sha256=)
3. Utilisez une comparaison à temps constant pour prévenir les attaques temporelles

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Tester un webhook

Cliquez sur le bouton Tester à côté d’un webhook pour envoyer un payload d’exemple à son endpoint. Le payload de test a "event": "test" et un champ data.message. Utilisez un outil comme webhook.site  pour inspecter la requête livrée.

Journal de livraison

Le journal de livraison affiche les 50 dernières tentatives de livraison pour chaque webhook, incluant :

• Événement — quel événement a été livré
• Statut — success ou failed
• Code de réponse — code de statut HTTP de l’endpoint
• Tentatives — nombre de tentatives de livraison (y compris les nouvelles tentatives)
• Heure — quand la livraison a été tentée

Comportement de nouvelle tentative

Lorsqu’une livraison de webhook échoue (réponse 5xx ou timeout réseau), SupDesk effectue jusqu’à 3 nouvelles tentatives avec backoff exponentiel :

Les erreurs client (4xx) ne font pas l’objet de nouvelles tentatives — elles indiquent un problème permanent avec la configuration de l’endpoint.

Exigences de plan

Les webhooks sortants sont disponibles sur les plans Pro et Team.