Webhooks

Recevez des notifications en temps réel de Trousseau lorsque des événements utilisateur ou de groupe se produisent.

Vue d'ensemble

Trousseau peut envoyer des notifications webhook à votre application lorsque certains événements surviennent, comme des modifications d'appartenance à un groupe. Cela permet à votre application de réagir en temps réel sans polling.

Les webhooks sont configurés lors de l'intégration. Contactez l'équipe KeySuite pour configurer la livraison des webhooks pour votre application.

Événements disponibles

Événement	Description	Déclencheur
`group_membership_change`	Utilisateur ajouté ou retiré d'un groupe	Modification des accès utilisateur
`user_updated`	Informations du profil utilisateur modifiées	Nom, e-mail, avatar mis à jour
`user_deactivated`	Compte utilisateur désactivé	Compte suspendu

Format des webhooks

Trousseau envoie les webhooks sous forme de requêtes HTTP POST avec un corps JSON :

POST https://app.yourapp.com/api/webhooks/trousseau
Content-Type: application/json
X-Trousseau-Signature: sha256=abc123...

Payload de l'événement

{
  "event_type": "group_membership_change",
  "timestamp": "2026-04-06T10:30:00Z",
  "data": {
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_email": "jean.dupont@hotel.com",
    "group_name": "Your App Users",
    "action": "added"
  }
}

Vérification des signatures de webhook

Chaque webhook inclut un en-tête X-Trousseau-Signature. Vérifiez-le pour vous assurer que la requête provient bien de Trousseau :

import crypto from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace("sha256=", "")),
    Buffer.from(expected)
  );
}

Vérifiez toujours la signature avant de traiter un webhook. Sans vérification, un attaquant pourrait envoyer de faux événements à votre endpoint.

Répondre aux webhooks

Retournez HTTP 200 pour accuser réception
Retournez HTTP 5xx pour déclencher une nouvelle tentative (Trousseau réessaie jusqu'à 3 fois avec un backoff exponentiel)
Traitez les webhooks de manière asynchrone s'ils déclenchent des opérations lentes

Bonnes pratiques

Traitement idempotent: Gérez gracieusement la réception du même événement deux fois
Vérification des signatures: Contrôlez toujours l'en-tête X-Trousseau-Signature
Utilisation de HTTPS: Les endpoints de webhook doivent utiliser HTTPS
Répondez rapidement: Retournez 200 dans les 5 secondes ; traitez de manière asynchrone si nécessaire