Webhooks de messages entrants (écouteurs)

Un écouteur (listener) relie l'un de vos numéros WhatsApp à Unibox et peut envoyer un webhook de message entrant à votre serveur. Dans le tableau de bord, les écouteurs se gèrent sur la page Déclencheurs entrants. Une fois qu'un numéro est un écouteur, ses discussions sont synchronisées dans la boîte de réception Unibox et, si vous ajoutez une URL de webhook, Wbiztool envoie chaque nouveau message à votre serveur. Utilisez les webhooks pour enregistrer les conversations dans un CRM, alerter votre équipe ou créer une réponse automatique.

Avant de commencer#

• L'option Unibox. Elle coûte 20 $/mois ou 200 $/an par numéro WhatsApp, et le nombre d'écouteurs dont vous pouvez disposer est égal à la quantité de l'option. Achetez-la sous Modules Complémentaires Disponibles dans Facturation et forfaits, dans le tableau de bord. Sans elle, la page Déclencheurs entrants s'ouvre quand même, mais cliquer sur Ajouter un Nouvel Écouteur affiche Unibox Add-on Required (option Unibox requise) avec un bouton Subscribe to Unibox Add-on (s'abonner à l'option Unibox).
• Un numéro WhatsApp connecté dans les paramètres WhatsApp. Seuls les numéros connectés qui ne sont pas encore des écouteurs peuvent être ajoutés.
• Vous devez être propriétaire (owner) ou éditeur de l'espace de travail.
• Pour les webhooks : une URL publique (utilisez https) de 100 caractères maximum qui accepte les requêtes POST avec un corps JSON.

Ajouter un écouteur#

1. Ouvrez Déclencheurs entrants

   Dans la barre latérale, ouvrez Unibox et cliquez sur Déclencheurs entrants, ou allez sur Déclencheurs entrants.

2. Créez un nouvel écouteur

   Cliquez sur la carte Ajouter un Nouvel Écouteur.

3. Choisissez le numéro

   Choisissez-le dans Sélectionner le numéro WhatsApp. Si la liste indique No available WhatsApp numbers (aucun numéro WhatsApp disponible), tous les numéros connectés sont déjà des écouteurs, ou aucun numéro n'est connecté.

4. Ajoutez un webhook (facultatif)

   Saisissez votre URL Webhook (Optionnel). Dès que vous saisissez une URL, Webhook Events (événements du webhook) apparaît : laissez cochés Incoming Messages (messages entrants), Outgoing Messages (messages sortants) ou les deux. Vous pourrez ajouter ou modifier l'URL plus tard.

5. Enregistrez

   Cliquez sur Ajouter un Écouteur. L'écouteur apparaît sous forme de carte avec le statut Active (actif). Si vous avez saisi une URL, un secret de webhook est créé pour celle-ci.

Gérer les écouteurs#

Chaque carte affiche le numéro, son statut, l'URL Webhook : (ou Non configuré), la Dernière Activité : (la dernière vérification des messages du numéro, ou Jamais) et le Secret Webhook :, masqué jusqu'à ce que vous cliquiez sur le bouton en forme d'œil.

Ouvrez le menu ⋮ d'une carte pour :

Statuts des écouteurs#

Statistiques#

Modifier l'URL ou les événements du webhook#

1. Ouvrez l'écouteur

   Cliquez sur ⋮ sur la carte, puis sur Modifier.

2. Mettez à jour les paramètres

   Modifiez Webhook URL (Optional) (URL du webhook, facultative) et Webhook Events. Effacez l'URL pour arrêter les webhooks de ce numéro : son secret est alors supprimé aussi, et un nouveau secret est créé si vous ajoutez à nouveau une URL.

3. Enregistrez

   Cliquez sur Update Listener (mettre à jour l'écouteur).

Régénérer le secret#

Dans Edit Listener (modifier l'écouteur), cliquez sur le bouton d'actualisation à côté de Webhook Secret (secret du webhook) et confirmez. Le nouveau secret est enregistré immédiatement, même si vous fermez ensuite la fenêtre sans cliquer sur Update Listener, et les requêtes sont signées avec ce secret à partir de ce moment. Mettez immédiatement à jour votre serveur avec le nouveau secret.

Comment les webhooks sont envoyés#

Wbiztool envoie une requête POST à votre URL pour chaque nouveau message trouvé lors de la synchronisation du numéro, qui a lieu toutes les quelques minutes tant que le numéro est connecté et n'est pas occupé à envoyer des messages.

• Événements : message_received pour les messages que l'on envoie à votre numéro, et message_sent pour les messages envoyés depuis celui-ci (depuis le téléphone, des campagnes ou l'API). Seuls les événements cochés dans Webhook Events sont envoyés.
• Les réponses envoyées depuis la boîte de réception Unibox ne déclenchent généralement pas message_sent, car la boîte de réception les contient déjà au moment de la synchronisation.
• Réponse : répondez avec un HTTP 200 en moins de 8 secondes. Toute autre réponse, ou un dépassement de délai, compte comme un échec de livraison.
• Aucune nouvelle tentative : chaque message n'est envoyé qu'une fois. Si votre serveur est indisponible, ce webhook est perdu.
• Ordre : les requêtes sont envoyées indépendamment et peuvent arriver dans le désordre. Triez selon message.timestamp si l'ordre compte.

En-têtes#

Payload#

{
  "event": "message_received",
  "timestamp": "2026-09-16T10:31:12.482913+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Hi, is my order #4821 out for delivery?",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:29:58+00:00",
    "whatsapp_timestamp": 1789554598,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-09-16T10:33:40.117205+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Yes, it will reach you today by 6 PM.",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:31:04+00:00",
    "whatsapp_timestamp": 1789554664,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-09-16T10:36:02.904311+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:34:51+00:00",
    "whatsapp_timestamp": 1789554891,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-09-16T10:40:15.330187+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Is the store open on Sunday?",
    "from": "120363041234567890",
    "from_name": "Acme Loyalty Club",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:39:02+00:00",
    "whatsapp_timestamp": 1789555142,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "name": "Acme Loyalty Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  },
  "group": {
    "name": "Acme Loyalty Club"
  }
}

Les numéros, identifiants et noms ci-dessus sont des exemples.

Champs de premier niveau#

Champs de message#

Champs de contact#

Vérifier la signature#

Chaque requête est signée avec le secret de votre écouteur au moyen de HMAC-SHA256. La signature est calculée sur le corps brut de la requête, exactement tel qu'il est reçu, et envoyée dans X-Wbiztool-Signature sous la forme sha256= suivi du condensat hexadécimal en minuscules.

Calculez toujours la signature à partir des octets bruts, avant d'analyser le JSON. Analyser puis réencoder le corps le modifie (par exemple, les caractères non anglais et les emoji arrivent échappés sous la forme \uXXXX), et la signature ne correspondra pas.

// Express: keep the raw body for this route
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // reply quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

La signature ne couvre pas l'en-tête d'horodatage : elle ne protège donc pas contre le rejeu d'une requête. Si c'est important pour vous, enregistrez chaque message.id déjà traité et ignorez les répétitions.

Dépannage#

Voir aussi#

• Boîte de réception Unibox
• Tickets
• Intégration Zapier
• API d'envoi de messages
• Forfaits et facturation