Introduction Configurer les webhooks Types d'événements Format des données (payload) Vérifier les signatures Nouvelles tentatives et désactivation automatique Bonnes pratiques

Webhooks du chat en direct

Les webhooks permettent à onWebChat d'envoyer des événements à votre propre serveur en temps réel. Chaque fois que quelque chose se produit (un nouveau chat commence, un message est envoyé, un chat est fermé ou évalué, un visiteur laisse un message hors ligne), nous envoyons une requête HTTP POST avec un corps JSON à l'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 interrogation régulière (polling).

Les webhooks sont disponibles sur tous les plans payants et pendant l'essai gratuit de 14 jours. Chaque envoi est signé pour que vous puissiez vérifier qu'il provient vraiment d'onWebChat.



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

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

Configurer les webhooks

Connectez-vous à votre tableau de bord en tant qu'administrateur et allez dans Paramètres → Webhooks. Cliquez sur « Ajouter un point de terminaison », collez l'URL qui doit recevoir les événements, choisissez les événements souhaités (ou sélectionnez « Tous les événements », qui couvre aussi les événements que nous ajouterons plus tard) et enregistrez.

Lorsque vous créez un point de terminaison, nous générons pour lui un secret de signature (il commence par whsec_). Vous utiliserez ce secret pour vérifier les requêtes entrantes (voir Vérifier les signatures ci-dessous). Vous pouvez régénérer le secret à tout moment ; l'ancien cesse alors immédiatement de fonctionner.

Vous pouvez ajouter plusieurs points de terminaison par site web et consulter les envois récents, avec le statut HTTP, le nombre de tentatives et les éventuelles erreurs, 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énements

Abonnez-vous à n'importe quelle combinaison des événements ci-dessous. Chaque message porte un champ "author" : visitor, agent ou ai (plus trigger, pour les messages de déclencheurs dans la transcription de chat.closed). Le même événement message.created couvre donc les conversations gérées par votre équipe et par le chatbot IA.

Événement	Envoyé lorsque
`chat.created`	Un nouveau chat (dialogue) commence. Le champ source indique comment : visitor, trigger ou agent.
`chat.assigned`	Un agent prend en charge un chat : il le récupère, le reprend à un autre agent ou au chatbot IA, ou accepte un transfert. Le champ source vaut pickup, reassign, ai_takeover ou transfer.
`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. Les données incluent la transcription complète, les informations sur le visiteur et les étiquettes.
`chat.rated`	Un visiteur évalue un chat (de 1 à 5 étoiles).
`offline_message.created`	Un visiteur envoie le formulaire hors ligne / de contact alors qu'aucun agent n'est disponible.
`visitor.updated`	Un agent met à jour le nom, l'e-mail, le téléphone ou les notes du visiteur depuis le tableau de bord du chat.
`visitor.banned`	Un agent bloque un visiteur depuis le tableau de bord du chat.
`visitor.unbanned`	Un agent débloque un visiteur précédemment bloqué depuis le tableau de bord du chat.

Format des données (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 les données d'un événement chat.closed, qui contiennent toute la conversation. Les événements plus légers comme message.created ou chat.rated n'incluent que les champs utiles.


{
  "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": "",
      "notes": "",
      "country_code": "us",
      "country": "United States",
      "os": "Windows 10",
      "browser": "Chrome 149.0"
    },
    "agents": ["Alex"],
    "labels": [{ "name": "sales", "color": "#4caf50" }],
    "messages": [
      { "author": "visitor", "agent_name": "", "text": "pricing info please", "time": "10:40", "date": "22-06-2026" },
      { "author": "ai", "agent_name": "", "text": "Here is a quick overview...", "time": "10:40", "date": "22-06-2026" },
      { "author": "agent", "agent_name": "Alex", "text": "Hi Sarah, I can help with a quote.", "time": "10:41", "date": "22-06-2026" }
    ]
  }
}

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 point de terminaison.

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 à temps constant et hachez toujours le corps brut, jamais une version resérialisée.

Vous recevez aussi X-OWC-Event (le nom de l'événement) et X-OWC-Delivery (un identifiant d'envoi unique qui reste le même lors des nouvelles tentatives, utile pour la déduplication). Les requêtes sont envoyées avec le User-Agent onWebChat-Webhooks/1.0.


// 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);

Nouvelles tentatives et désactivation automatique

Votre point de terminaison doit répondre avec un statut 2xx le plus rapidement possible, et en 10 secondes au maximum. Toute réponse autre que 2xx, tout délai dépassé ou toute erreur de connexion est considéré comme une tentative échouée.

Les envois échoués sont retentés avec un délai croissant : après 1 minute, 5 minutes, 20 minutes, 1 heure et 2 heures (6 tentatives au total).

Si 5 envois consécutifs échouent encore après toutes leurs nouvelles tentatives, le point de terminaison est désactivé automatiquement et le propriétaire du compte reçoit un e-mail. Réactivez-le depuis le tableau de bord une fois le problème résolu. Une réponse HTTP 410 (Gone) désactive immédiatement le point de terminaison.



    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 failed deliveries in a row → endpoint disabled

Bonnes pratiques

Vérifiez toujours l'en-tête X-OWC-Signature avant de faire confiance aux données reçues.
Répondez rapidement avec un statut 2xx, puis effectuez les traitements lourds de manière asynchrone (via une file d'attente) pour éviter de dépasser le délai.
Utilisez X-OWC-Delivery pour dédupliquer, car un même envoi peut être retenté après un échec passager.
Servez votre point de terminaison en HTTPS.
Ignorez les types d'événements inconnus, pour que les nouveaux événements que nous ajouterons ne cassent pas votre intégration.

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