Webhooks für eingehende Nachrichten (Listener)

Ein Listener verbindet eine Ihrer WhatsApp-Nummern mit Unibox und kann einen Webhook für eingehende Nachrichten an Ihren Server senden. Im Dashboard werden Listener auf der Seite Eingehende Trigger verwaltet. Sobald eine Nummer ein Listener ist, werden ihre Chats in den Unibox-Posteingang synchronisiert, und wenn Sie eine Webhook-URL angeben, sendet Wbiztool jede neue Nachricht an Ihren Server. Nutzen Sie Webhooks, um Unterhaltungen in einem CRM zu protokollieren, Ihr Team zu benachrichtigen oder eine automatische Antwort zu bauen.

Bevor Sie beginnen#

• Das Unibox-Add-on. Es kostet 20 $/Monat oder 200 $/Jahr pro WhatsApp-Nummer, und die Anzahl möglicher Listener entspricht der gebuchten Menge des Add-ons. Kaufen Sie es unter Verfügbare Add-ons auf der Seite Abrechnung & Pläne im Dashboard. Ohne das Add-on öffnet sich die Seite Eingehende Trigger zwar, aber ein Klick auf Neuen Listener hinzufügen zeigt Unibox Add-on Required (Unibox-Add-on erforderlich) mit einer Schaltfläche Subscribe to Unibox Add-on (Unibox-Add-on abonnieren).
• Eine verbundene WhatsApp-Nummer in den WhatsApp-Einstellungen. Nur verbundene Nummern, die noch keine Listener sind, können hinzugefügt werden.
• Sie müssen Inhaber oder Bearbeiter des Arbeitsbereichs sein.
• Für Webhooks: eine öffentliche URL (verwenden Sie https) mit höchstens 100 Zeichen, die POST-Anfragen mit JSON-Body annimmt.

Listener hinzufügen#

1. Eingehende Trigger öffnen

   Öffnen Sie in der Seitenleiste Unibox und klicken Sie auf Eingehende Trigger, oder rufen Sie Eingehende Trigger auf.

2. Neuen Listener anlegen

   Klicken Sie auf die Karte Neuen Listener hinzufügen.

3. Nummer auswählen

   Wählen Sie sie unter WhatsApp-Nummer auswählen aus. Zeigt die Liste Keine verfügbaren WhatsApp-Nummern, ist jede verbundene Nummer bereits ein Listener oder es ist keine verbunden.

4. Webhook hinzufügen (optional)

   Geben Sie Ihre Webhook-URL (Optional) ein. Sobald Sie eine URL eingeben, erscheint Webhook Events (Webhook-Ereignisse): Lassen Sie Incoming Messages (eingehende Nachrichten), Outgoing Messages (ausgehende Nachrichten) oder beide angehakt. Sie können die URL später hinzufügen oder ändern.

5. Speichern

   Klicken Sie auf Listener hinzufügen. Der Listener erscheint als Karte mit dem Status Active (Aktiv). Wenn Sie eine URL eingegeben haben, wird dafür ein Webhook-Geheimnis erstellt.

Listener verwalten#

Jede Karte zeigt die Nummer, ihren Status, die Webhook-URL: (oder Nicht konfiguriert), Letzte Aktivität: (wann die Nummer zuletzt auf Nachrichten geprüft wurde, oder Niemals) und das Webhook-Geheimnis:, das verborgen ist, bis Sie auf das Augen-Symbol klicken.

Öffnen Sie das Menü ⋮ auf einer Karte, um:

Listener-Status#

Statistiken#

Webhook-URL oder Ereignisse ändern#

1. Listener öffnen

   Klicken Sie auf der Karte auf ⋮ und dann auf Bearbeiten.

2. Einstellungen aktualisieren

   Ändern Sie die Webhook-URL (Optional) und die Webhook Events. Leeren Sie die URL, um Webhooks für diese Nummer zu beenden: Dabei wird auch das Geheimnis entfernt, und ein neues wird erstellt, wenn Sie wieder eine URL hinzufügen.

3. Speichern

   Klicken Sie auf Update Listener (Listener aktualisieren).

Geheimnis neu generieren#

Klicken Sie in Edit Listener (Listener bearbeiten) auf die Aktualisieren-Schaltfläche neben Webhook Secret (Webhook-Geheimnis) und bestätigen Sie. Das neue Geheimnis wird sofort gespeichert, auch wenn Sie den Dialog anschließend schließen, ohne auf Update Listener zu klicken, und Anfragen werden ab dann damit signiert. Aktualisieren Sie das Geheimnis sofort auf Ihrem Server.

Wie Webhooks zugestellt werden#

Wbiztool sendet für jede neue Nachricht, die bei der Synchronisierung der Nummer gefunden wird, eine POST-Anfrage an Ihre URL. Die Synchronisierung erfolgt alle paar Minuten, solange die Nummer verbunden ist und nicht mit dem Senden von Nachrichten beschäftigt ist.

• Ereignisse: message_received für Nachrichten, die Personen an Ihre Nummer senden, und message_sent für Nachrichten, die von ihr gesendet werden (vom Smartphone, aus Kampagnen oder über die API). Es werden nur die unter Webhook Events angehakten Ereignisse gesendet.
• Antworten aus dem Unibox-Posteingang lösen message_sent in der Regel nicht aus, weil der Posteingang sie bei der Synchronisierung bereits enthält.
• Antwort Ihres Servers: Antworten Sie innerhalb von 8 Sekunden mit HTTP 200. Jede andere Antwort oder eine Zeitüberschreitung gilt als fehlgeschlagene Zustellung.
• Keine Wiederholungen: Jede Nachricht wird einmal gesendet. Ist Ihr Server nicht erreichbar, geht dieser Webhook verloren.
• Reihenfolge: Anfragen werden unabhängig voneinander gesendet und können in anderer Reihenfolge ankommen. Sortieren Sie nach message.timestamp, wenn die Reihenfolge wichtig ist.

Header#

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"
  }
}

Die oben gezeigten Nummern, IDs und Namen sind Beispiele.

Felder der obersten Ebene#

Felder von message#

Felder von contact#

Signatur prüfen#

Jede Anfrage wird mit dem Geheimnis Ihres Listeners per HMAC-SHA256 signiert. Die Signatur wird über den rohen Request-Body genau so, wie er empfangen wurde, berechnet und als sha256= plus hexadezimaler Digest in Kleinbuchstaben in X-Wbiztool-Signature gesendet.

Berechnen Sie die Signatur immer aus den rohen Bytes, bevor Sie das JSON parsen. Wird der Body geparst und neu kodiert, ändert er sich (zum Beispiel kommen nicht-englische Zeichen und Emojis als \uXXXX maskiert an), und die Signatur stimmt nicht mehr überein.

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

Die Signatur umfasst den Timestamp-Header nicht und schützt daher nicht davor, dass eine Anfrage erneut abgespielt wird (Replay). Falls das für Sie wichtig ist, speichern Sie jede verarbeitete message.id und ignorieren Sie Wiederholungen.

Fehlerbehebung#

Verwandte Themen#

• Unibox-Posteingang
• Tickets
• Zapier-Integration
• Send Message API
• Pläne und Abrechnung