Documentation Trustdio

Webhooks

Événements émis, format, signature HMAC, retry.

Les webhooks vous permettent d'être notifié en temps réel des événements Trustdio (nouveau message, lead qualifié, conversation fermée…), sans polling de l'API.

Configurer un webhook

Paramètres → API & webhooks → + Nouveau webhook. 3 champs :

  • URL d'endpoint — votre serveur, HTTPS obligatoire en prod
  • Événements à écouter — sélectionnez parmi la liste (multi-choix)
  • Secret HMAC — généré automatiquement, à stocker côté serveur pour vérifier la signature

Événements disponibles

  • conversation.created — nouvelle conversation démarrée
  • conversation.closed — fermée (résolue / abandonnée / escaladée)
  • message.received — nouveau message (user ou opérateur)
  • lead.qualified — lead score > seuil configuré
  • contact.created — nouveau contact CRM
  • contact.updated — champ modifié (tag, segment…)
  • operator.takeover — un opérateur reprend la main
  • kb.article_created / kb.article_updated
  • workflow.executed — workflow déclenché (incluant succès/échec)

Format du payload

Tous les webhooks sont POST en JSON :

jsonpayload-message-received.json
1{
2  "id": "evt_2k4d8x...",
3  "event": "message.received",
4  "createdAt": "2026-05-20T14:32:11.234Z",
5  "data": {
6    "conversation": {
7      "id": "conv_2k4d8x",
8      "channel": "widget",
9      "url": "https://app.trustdio.fr/inbox/conv_2k4d8x"
10    },
11    "contact": {
12      "id": "cnt_8b3...",
13      "email": "client@exemple.fr",
14      "name": "Sophie Dupont"
15    },
16    "message": {
17      "id": "msg_xq3...",
18      "text": "Bonjour, je cherche un avocat en droit du travail",
19      "type": "user",
20      "language": "fr",
21      "sentiment": "neutral"
22    }
23  }
24}

Vérifier la signature HMAC

Chaque requête contient un header X-Trustdio-Signature au format t=timestamp,v1=hash. Vérifiez-le pour confirmer que la requête vient bien de Trustdio.

javascriptverify-webhook.js
1import crypto from "node:crypto";
2import express from "express";
3 
4const app = express();
5app.use(express.raw({ type: "application/json" }));
6 
7const SECRET = process.env.TRUSTDIO_WEBHOOK_SECRET;
8 
9app.post("/webhooks/trustdio", (req, res) => {
10  const signature = req.headers["x-trustdio-signature"];
11  const [tPart, v1Part] = signature.split(",");
12  const timestamp = tPart.split("=")[1];
13  const expectedHash = v1Part.split("=")[1];
14 
15  // Reject if older than 5 min (replay protection)
16  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
17    return res.status(401).send("Timestamp too old");
18  }
19 
20  // Compute expected HMAC
21  const payload = `${timestamp}.${req.body.toString()}`;
22  const computed = crypto
23    .createHmac("sha256", SECRET)
24    .update(payload)
25    .digest("hex");
26 
27  // Constant-time comparison
28  if (!crypto.timingSafeEqual(
29    Buffer.from(computed),
30    Buffer.from(expectedHash)
31  )) {
32    return res.status(401).send("Invalid signature");
33  }
34 
35  // ✅ Signature valid, process the event
36  const event = JSON.parse(req.body.toString());
37  console.log("Received:", event.event, event.data);
38 
39  res.status(200).send("ok");
40});

Retry & idempotence

  • Retry automatique sur erreur HTTP 5xx ou timeout (10s max)
  • Backoff exponentiel : 1s, 5s, 30s, 2min, 10min, 1h, 6h (7 tentatives total)
  • Idempotence : utilisez id du payload pour dédupliquer côté serveur
  • Désactivation auto après 50 échecs consécutifs (notification email)

Tester en local

Utilisez ngrok ou cloudflared pour exposer votre serveur local :

bash
1# Lancer votre serveur local sur :3000
2ngrok http 3000
3 
4# Copier l'URL HTTPS générée (ex: https://abc123.ngrok.io)
5# Configurer cette URL dans Paramètres → Webhooks

Logs & debugging

Paramètres → API & webhooks → Historique affiche les 100 dernières livraisons : statut HTTP, payload envoyé, response reçue, durée. Replay possible en 1 clic.

Et après ?

Cette page vous a été utile ?

Modifié le · Suggérer une amélioration