Webhooks

Les webhooks vous permettent de recevoir des notifications en temps reel lorsque des evenements se produisent dans votre widget de chat. Lorsqu'un visiteur demarre un chat, soumet un formulaire ou envoie un message, Chatim envoie une requete HTTP POST a votre URL avec les donnees de l'evenement.

Apercu

Avec les webhooks vous pouvez :

• Envoyer automatiquement de nouveaux leads a votre CRM
• Declencher des workflows dans Zapier, Make ou des applications personnalisees
• Enregistrer les evenements de chat dans votre plateforme d'analyse
• Notifier votre equipe dans Slack ou d'autres outils
• Synchroniser les donnees des visiteurs avec votre base de donnees

Acceder aux Webhooks

1. Connectez-vous a votre tableau de bord Chatim
2. Selectionnez votre projet dans la barre laterale
3. Cliquez sur Webhooks dans le menu de navigation

Creer un Webhook

1. Cliquez sur Creer un Webhook
2. Saisissez un Nom optionnel (ex., "Integration CRM")
3. Saisissez l'URL ou les evenements doivent etre envoyes
4. Selectionnez un ou plusieurs Evenements que vous souhaitez recevoir
5. Cliquez sur Creer

Apres la creation, vous verrez un Secret du Webhook - copiez-le et sauvegardez-le immediatement. Ce secret est utilise pour verifier que les requetes entrantes proviennent de Chatim. Il n'est affiche qu'une seule fois.

Evenements pris en charge

Charge utile du Webhook

Chaque livraison de webhook est une requete HTTP POST avec un corps JSON.

Champs communs

{
  "event": "chat.started",
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "projectUuid": "your-project-uuid",
  "chatUuid": "visitor-chat-uuid",
  "data": { }
}

chat.started

Inclut les informations du visiteur, l'URL de la page, la localisation et l'agent utilisateur.

{
  "event": "chat.started",
  "data": {
    "visitor": {
      "uuid": "visitor-uuid",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "page": {
      "url": "https://example.com/pricing",
      "title": "Pricing - Example"
    },
    "location": { "country": "US", "city": "Los Angeles" },
    "userAgent": { "browser": "Chrome", "os": "Windows", "device": "Desktop" }
  }
}

chat.message.received

{
  "event": "chat.message.received",
  "data": {
    "messageUuid": "message-uuid",
    "message": "Hi, I have a question about your pricing.",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.form.submitted

{
  "event": "chat.form.submitted",
  "data": {
    "formNodeId": "node-id",
    "formName": "Contact Form",
    "fields": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "message": "I'd like a product demo."
    },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.closed

Inclut qui a ferme le chat (agent, visitor, system ou timeout), la duree en secondes, le nombre de messages et la transcription.

{
  "event": "chat.closed",
  "data": {
    "closedBy": "agent",
    "status": "closed",
    "duration": 345,
    "messageCount": 12,
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.assigned

Envoye lorsqu'un agent de support rejoint la conversation.

{
  "event": "chat.assigned",
  "data": {
    "assignedTo": { "uuid": "agent-uuid", "name": "Jane Smith" },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.handoff

Envoye lorsque le chatbot passe en mode chat en direct.

{
  "event": "chat.handoff",
  "data": {
    "reason": "Visitor requested human support",
    "fromNode": "node-id",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

Securite

Verification de la signature

Chaque requete webhook inclut une signature pour que vous puissiez verifier qu'elle provient de Chatim. La signature est calculee comme HMAC-SHA256(secret, timestamp + "." + payload) et envoyee dans l'en-tete X-Chatim-Signature.

En-tetes de requete

Exemple de verification Node.js

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-chatim-signature'];
  const timestamp = req.headers['x-chatim-timestamp'];
  const body = JSON.stringify(req.body);

  // Reject requests older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

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

Exemple de verification Python

import hmac, hashlib, time

def verify_webhook(headers, body, secret):
    signature = headers.get('X-Chatim-Signature', '')
    timestamp = headers.get('X-Chatim-Timestamp', '')

    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        f'{timestamp}.{body}'.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Logique de reessai

Si votre endpoint est indisponible ou renvoie une erreur, Chatim reessaie automatiquement.

Apres 5 tentatives echouees, la livraison est marquee comme echouee. Les reponses 2xx sont traitees comme un succes, 4xx comme des echecs permanents (pas de reessai), 5xx et les depassements de delai (30s) declenchent des reessais.

Si un webhook accumule 10 echecs consecutifs, il est automatiquement desactive. Vous pouvez le reactiver depuis le tableau de bord apres avoir corrige le probleme.

Gerer les Webhooks

Tests

Cliquez sur Tester sur n'importe quel webhook pour envoyer un evenement exemple chat.started a votre URL. Cela vous permet de verifier votre endpoint avant la mise en production.

Historique des livraisons

Cliquez sur un webhook pour voir les livraisons recentes avec le type d'evenement, l'horodatage, le code de statut HTTP et les messages d'erreur. L'historique est conserve pendant 30 jours.

Regenerer un secret

Si votre secret de webhook est compromis, cliquez sur Regenerer le secret, sauvegardez le nouveau secret et mettez a jour votre endpoint. L'ancien secret est immediatement invalide.

Cas d'utilisation

Integration CRM

Abonnez-vous a chat.form.submitted et chat.started pour creer automatiquement des contacts et des leads dans votre CRM.

Notifications Slack

Abonnez-vous a chat.assigned et chat.handoff pour alerter votre equipe quand un visiteur a besoin de support en direct.

Analyse

Abonnez-vous a tous les evenements pour construire une image complete de l'engagement chat, des taux de conversion de formulaires et des temps de reponse du support.

Automatisation email

Abonnez-vous a chat.form.submitted pour declencher des emails de bienvenue, des sequences de suivi ou des messages de confirmation.

Bonnes pratiques

• Renvoyez une reponse 2xx rapidement - traitez les donnees de maniere asynchrone
• Utilisez HTTPS pour l'URL de votre endpoint
• Verifiez toujours la signature du webhook avant le traitement
• Implementez l'idempotence en utilisant l'eventId pour gerer les livraisons en double
• Stockez votre secret de webhook en securite (variable d'environnement, gestionnaire de secrets)
• Validez l'horodatage pour prevenir les attaques par rejeu (rejetez les requetes de plus de 5 minutes)

Depannage

Le Webhook ne recoit pas d'evenements

1. Verifiez que le webhook est Actif (pas desactive)
2. Verifiez que l'URL est correcte et accessible publiquement
3. Utilisez le bouton Tester pour envoyer un evenement exemple
4. Verifiez les journaux de votre serveur pour les requetes entrantes
5. Assurez-vous que votre endpoint renvoie un code de statut 2xx

Webhook desactive automatiquement

1. Verifiez la raison de la desactivation dans le tableau de bord
2. Corrigez le probleme sous-jacent (endpoint en panne, renvoi d'erreurs)
3. Cliquez sur Activer pour reactiver
4. Utilisez Tester pour verifier avant la reactivation

La verification de signature echoue

1. Assurez-vous d'utiliser le bon secret
2. Verifiez que vous signez timestamp + "." + raw_body (pas du JSON parse)
3. Utilisez une comparaison securisee en temps pour prevenir les attaques temporelles