Webhooks de Chat en Direct

Les webhooks permettent à onWebChat d'envoyer des événements à votre serveur en temps réel. Chaque fois que quelque chose se produit dans un chat : une nouvelle conversation commence, un message est envoyé, un chat est fermé, noté, ou un message hors ligne est laissé, nous envoyons un HTTP POST avec un corps JSON à une URL de votre choix.

C'est le moyen le plus simple de synchroniser les transcriptions de chat dans votre CRM ou CMS, de déclencher des e-mails de suivi, de créer des rapports personnalisés ou de notifier un autre système, sans polling.

Les webhooks sont disponibles sur tous les plans payants. Chaque livraison est signée pour que vous puissiez vérifier qu'elle provient vraiment d'onWebChat.



POST https://your-server.com/onwebchat-webhook
Content-Type: application/json
X-OWC-Event: chat.closed
X-OWC-Delivery: 9381
X-OWC-Signature: sha256=4f1c...c2a9

{ "event": "chat.closed", "siteid": 1234, ... }

Configurer les Webhooks

Ouvrez votre tableau de bord et allez dans Paramètres → Webhooks. Cliquez sur "Ajouter un endpoint", collez l'URL qui doit recevoir les événements, choisissez les événements souhaités (ou sélectionnez "Tous les événements") et sauvegardez.

Lors de la création d'un endpoint, nous générons un secret de signature. Vous utiliserez ce secret pour vérifier les requêtes entrantes (voir Vérifier les Signatures). Vous pouvez le régénérer à tout moment.

Vous pouvez ajouter plusieurs endpoints par site web et consulter les livraisons récentes, y compris le statut HTTP, le nombre de tentatives et toute erreur, directement dans le tableau de bord.



/* Dashboard → Settings → Webhooks */

URL      : https://your-server.com/onwebchat-webhook
Events   : chat.closed, message.created
Secret   : whsec_3f9a...   (used to verify requests)
Status   : Enabled

Types d'Événement

Abonnez-vous à n'importe quelle combinaison des événements ci-dessous. Chaque message est étiqueté avec un "author" de visitor, agent, ai ou trigger, ainsi le même événement message.created couvre les conversations gérées par votre équipe et par le chatbot IA.

Événement	Envoyé lorsque
`chat.created`	Un nouveau chat est démarré par un visiteur, un trigger, le chatbot IA ou un agent.
`chat.assigned`	Un agent prend en charge une conversation : il la récupère, prend le relais du bot IA ou accepte un transfert.
`message.created`	Un nouveau message est envoyé dans un chat. Inclut les messages du visiteur, d'un agent et du chatbot IA.
`chat.closed`	Un chat se termine. Le payload inclut la transcription complète, les détails du visiteur et les étiquettes.
`chat.rated`	Un visiteur note un chat.
`offline_message.created`	Un visiteur soumet le formulaire hors ligne en l'absence d'agent disponible.
`visitor.updated`	Un agent met à jour le nom, l'email, le téléphone ou les notes du visiteur depuis le tableau de bord.
`visitor.banned`	Un agent bloque un visiteur depuis le tableau de bord.
`visitor.unbanned`	Un agent débloque un visiteur précédemment bloqué depuis le tableau de bord.

Format du Payload

Chaque webhook est un objet JSON avec la même enveloppe : le nom de l'événement, votre siteid, un horodatage ISO-8601 et un objet de données dont la forme dépend de l'événement.

L'exemple montre un payload chat.closed, qui contient toute la conversation. Les événements plus petits comme message.created ou chat.rated n'incluent que les champs pertinents.


{
  "event": "chat.closed",
  "siteid": 1234,
  "created_at": "2026-06-22T07:40:52.322Z",
  "data": {
    "chat_id": 1206836,
    "started_at": "22-06-2026 10:40",
    "closed_at": "2026-06-22T07:40:52.322Z",
    "visitor": {
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "phone": "",
      "country": "United States",
      "os": "Windows 10",
      "browser": "Chrome 149.0"
    },
    "agents": ["Alex"],
    "labels": [{ "name": "sales", "color": "#4caf50" }],
    "messages": [
      { "author": "visitor", "text": "pricing info please", "time": "10:40" },
      { "author": "ai", "text": "Here is a quick overview...", "time": "10:40" }
    ]
  }
}

Vérifier les Signatures

Chaque requête inclut un en-tête X-OWC-Signature contenant un hash HMAC-SHA256 du corps brut exact de la requête, calculé avec le secret de signature de votre endpoint.

Pour vérifier une requête, calculez le HMAC-SHA256 du corps brut avec votre secret et comparez-le à la valeur de l'en-tête (la partie après "sha256="). Utilisez une comparaison en temps constant et hashez toujours le corps brut.

Vous recevez aussi X-OWC-Event (le nom de l'événement) et X-OWC-Delivery (un id unique pour l'idempotence).


// Node.js / Express
const crypto = require('crypto');

app.post('/onwebchat-webhook',
  express.raw({ type: '*/*' }), (req, res) => {

  const secret = 'whsec_your_secret';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)              // raw Buffer
    .digest('hex');

  const got = req.headers['x-owc-signature'] || '';

  // constant-time compare; guard length first (timingSafeEqual throws on mismatch)
  const a = Buffer.from(got), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end();

  const payload = JSON.parse(req.body.toString());
  // ... handle payload.event ...
  res.sendStatus(200);
});

Vérifier en PHP

La même vérification en PHP : lisez le corps brut, recalculez le HMAC avec votre secret et comparez avec hash_equals().


<?php
$secret  = 'whsec_your_secret';
$payload = file_get_contents('php://input');
$got     = $_SERVER['HTTP_X_OWC_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);
// ... handle $event['event'] ...
http_response_code(200);

Relances & Désactivation Automatique

Votre endpoint doit répondre avec un statut 2xx aussi rapidement que possible. Toute réponse non-2xx, un timeout ou une erreur de connexion est traitée comme un échec.

Les livraisons échouées sont relancées avec un délai croissant : après 1 minute, 5 minutes, 20 minutes, 1 heure et 2 heures.

Si un endpoint continue d'échouer (5 échecs consécutifs), il est automatiquement désactivé et le propriétaire du site est notifié. Réactivez-le depuis le tableau de bord. Renvoyer HTTP 410 le désactive immédiatement.



    Attempt 1  → immediately
    Attempt 2  → after  1 minute
    Attempt 3  → after  5 minutes
    Attempt 4  → after 20 minutes
    Attempt 5  → after  1 hour
    Attempt 6  → after  2 hours

    5 failures in a row → endpoint disabled

Bonnes Pratiques

Vérifiez toujours le X-OWC-Signature avant de faire confiance à un payload.
Répondez 2xx rapidement, puis effectuez le travail lourd de manière asynchrone pour ne pas expirer.
Utilisez X-OWC-Delivery pour dédupliquer, car la même livraison peut être relancée après un échec transitoire.
Servez votre endpoint en HTTPS.
Ignorez les types d'événements inconnus pour que les nouveaux événements ne cassent pas votre intégration.

Prêt à commencer ? Voir les plans ou ouvrez Paramètres → Webhooks dans votre tableau de bord.