Posteingangsnummern und Webhooks für eingehende Nachrichten

Auf der Seite Posteingangsnummern wählen Sie, welche Ihrer WhatsApp-Nummern in den Unibox-Posteingang synchronisiert werden, wo Ihr Team ihre Chats liest und beantwortet. Geben Sie einer Nummer eine Webhook-URL, und WbizTool sendet zusätzlich jede neue Nachricht, die sie empfängt oder sendet, als signiertes JSON an Ihren Server: Protokollieren Sie Unterhaltungen in einem CRM, alarmieren Sie Ihr Team oder lösen Sie eine automatische Antwort aus.

Sie bauen den Empfänger? Lesen Sie Wie Webhooks zugestellt werden, Signatur prüfen und Payload.

Wer darf das: Inhaber und Bearbeiter fügen Nummern hinzu, ändern Webhooks und sehen das Webhook-Secret. Analysten sehen Posteingangsnummern nicht in der Seitenleiste. Nötig ist das Unibox-Add-on: 20 $ pro Monat oder 200 $ pro Jahr zum US-Listenpreis für jede Nummer im Posteingang (Ihr Preis steht unter Abrechnung & Pläne), von einem Inhaber unter Abrechnung & Pläne zu einem bezahlten Plan oder Lifetime-Plan hinzugefügt (siehe Add-ons). Seine Menge gibt an, wie viele Nummern gleichzeitig im Posteingang sein können.

Öffnen Sie in der Seitenleiste unter Posteingang den Punkt Posteingangsnummern oder rufen Sie /unibox/listeners/ auf.

Bevor Sie beginnen#

• Das Unibox-Add-on mit einer freien Posteingangsnummer: Die Zeile unter dem Seitentitel sagt z. B. „2 von 3 Posteingangsnummern belegt (Unibox-Add-on)“ oder „Kein Unibox-Add-on“ (siehe Ohne Unibox-Add-on).
• Eine per QR-Code oder Kopplungscode verbundene WhatsApp-Nummer, die unter WhatsApp-Nummern als Verbunden angezeigt wird. Über die Browser-Erweiterung verbundene Nummern können nicht hinzugefügt werden. Ein verbundenes Telegram-Konto lässt sich wie eine Nummer hinzufügen.
• Für einen Webhook: eine https://-Adresse mit höchstens 500 Zeichen im öffentlichen Internet (nicht localhost oder ein privates Netzwerk), die POST-Anfragen mit JSON-Body annimmt und innerhalb von 8 Sekunden mit 2xx antwortet.

Nummer zum Posteingang hinzufügen#

1. Dialog öffnen

   Klicken Sie oben rechts auf der Seite auf Nummer zum Posteingang hinzufügen.

2. Nummer auswählen

   Wählen Sie sie unter WhatsApp-Nummer. Die Liste zeigt Ihre verbundenen Nummern, die noch nicht im Posteingang sind.

3. Webhook hinzufügen (optional)

   Geben Sie Ihre Adresse unter Webhook-URL (optional) ein. Dann erscheint Zu sendende Nachrichten: Lassen Sie Empfangene Nachrichten, Gesendete Nachrichten oder beide angehakt. Sie können den Webhook auch später hinzufügen oder ändern.

   

4. Hinzufügen

   Klicken Sie auf Nummer hinzufügen. Sie sehen „Nummer hinzugefügt – ihre Chats werden innerhalb weniger Minuten synchronisiert.“ Haben Sie eine Webhook-URL eingegeben, öffnet sich Ihr Webhook-Secret: Klicken Sie auf Kopieren und speichern Sie das Secret dort, wo Ihr Server es lesen kann. Sie können es später in den Webhook-Einstellungen erneut anzeigen.

• Nur neue Nachrichten. Eine Nummer wird ab dem Moment synchronisiert, in dem Sie sie hinzufügen: Ältere Nachrichten werden weder importiert noch gesendet.
• Alle Nummern belegt? Der Dialog sagt „Alle Ihre Posteingangsnummern sind belegt. Stoppen oder entfernen Sie eine oder erweitern Sie das Unibox-Add-on.“ Stoppen oder entfernen Sie eine Nummer, oder bitten Sie einen Inhaber, die Menge des Add-ons zu erhöhen (Add-ons ansehen).
• Eine entfernte Nummer wieder hinzufügen bringt ihren Posteingang zurück („Nummer wieder hinzugefügt – ihre Chats werden ab jetzt wieder synchronisiert.“); Nachrichten aus der Zeit, in der sie entfernt war, werden nicht abgeholt. Mit einer Webhook-URL behält sie ihr früheres Secret, falls sie eines hatte (nutzen Sie Anzeigen in den Webhook-Einstellungen); andernfalls öffnet sich Ihr Webhook-Secret mit einem neuen.

Was die Karte einer Nummer zeigt#

Jede Karte zeigt die Nummer, wann WbizTool sie zuletzt auf Nachrichten geprüft hat („Zuletzt geprüft: vor 1 Min.“ oder Nie geprüft), ihre Nachrichten und Synchronisierte Kontakte (jeder von ihr synchronisierte Chat, auch solche ohne Nachrichten im Posteingang), ihre Letzte Nachricht und ihren Webhook: die URL und was er sendet, z. B. „Sendet jede empfangene und gesendete Nachricht · mit einem Secret signiert“ oder „Keiner – Nachrichten erscheinen nur im Posteingang.“ Ein Zapier-Badge bedeutet, dass ein Zap die Nachrichten empfängt (siehe Zapier und Posteingangsnummern).

Das Badge oben rechts zeigt, was die Nummer gerade tut:

Webhook-URL oder gesendete Nachrichten ändern#

1. Webhook-Einstellungen öffnen

   Klicken Sie auf der Karte der Nummer auf Webhook-Einstellungen.

2. Einstellungen ändern

   Bearbeiten Sie die Webhook-URL (optional) und die Haken unter Zu sendende Nachrichten. Um den Webhook auszuschalten, leeren Sie die URL.

3. Speichern

   Klicken Sie auf Speichern. Sie sehen „Webhook-Einstellungen gespeichert.“

   

• Wenn Sie die URL ändern, bleibt das Secret erhalten. Wenn Sie die URL leeren, wird es gelöscht; eine später hinzugefügte URL bekommt ein neues Secret, das einmal in Ihr Webhook-Secret angezeigt wird.
• Ist keines der beiden Kästchen angehakt, steht auf der Karte „Keine Ereignisse gewählt – es wird nichts gesendet“.

Secret anzeigen oder neu erzeugen#

Das Secret besteht aus 32 Buchstaben und Ziffern. In den Webhook-Einstellungen zeigt Anzeigen es unter Webhook-Secret an, mit Kopieren daneben. Neu erzeugen fragt „Neues Secret erzeugen? Das aktuelle funktioniert sofort nicht mehr – aktualisieren Sie es überall, wo Sie Signaturen prüfen.“ Klicken Sie auf Neues Secret erzeugen: Es wird sofort gespeichert („Neues Secret erzeugt.“), ohne Speichern, und jede Anfrage ab dann wird damit signiert, auch Wiederholungen früherer Nachrichten.

Nummer stoppen, starten oder entfernen#

Webhooks, die auf eine Wiederholung warten, werden verworfen, wenn Sie die Nummer stoppen oder entfernen oder ihre URL ändern.

Wie Webhooks zugestellt werden#

• Wann: Jede Posteingangsnummer wird etwa einmal pro Minute geprüft, solange sie verbunden ist; die Prüfungen pausieren, während sie Nachrichten sendet, z. B. eine Kampagne. Eine Nachricht wird nach der Prüfung gesendet, die sie findet, meist innerhalb von ein bis zwei Minuten. Einen Test-Button gibt es nicht: Schicken Sie der Nummer von einem anderen Telefon eine Nachricht.
• Eine Anfrage pro Nachricht: message_received für Empfangene Nachrichten; message_sent für Gesendete Nachrichten, gesendet vom Telefon, über WhatsApp Web oder von WbizTool (Kampagnen, die API, Erinnerungen). Antworten aus dem Unibox-Posteingang werden meist nicht gesendet: Der Posteingang hat sie schon.
• Erfolg: jeder 2xx-Status innerhalb von 8 Sekunden. Weiterleitungen werden nicht verfolgt: Ein 3xx zählt als Fehlschlag.
• Wiederholungen: Eine Zeitüberschreitung, ein Verbindungsfehler, 429 oder ein 5xx wird 3-mal wiederholt, nach 30 Sekunden, 1 Minute und 2 Minuten. Andere Antworten wie 400 oder 404 sowie ein ungültiges TLS-Zertifikat werden nicht wiederholt.
• 410 Gone: WbizTool schaltet den Webhook der Nummer aus (URL und Secret werden entfernt; bei einem Zapier-Hook kommt Ihr eigener früherer Webhook zurück). Die Nummer synchronisiert weiter in den Posteingang.
• Reihenfolge und Duplikate: Anfragen können in anderer Reihenfolge und selten doppelt ankommen. Sortieren Sie nach message.whatsapp_timestamp und überspringen Sie eine message.id, die Sie für dieselbe whatsapp_client_id schon verarbeitet haben. Sind zwei Ihrer Nummern in einer Gruppe, sendet jede ihre eigene Kopie.
• Späte Nachrichten: Eine Nachricht, die spät abgeholt wird, etwa nachdem die Nummer neu verbunden wurde oder nach einer Pause der Prüfungen, wird trotzdem gesendet, mit replayed auf true, wenn sie älter als 10 Minuten ist. Nachrichten, die eingingen, während die Nummer gestoppt war, werden nach Starten nicht gesendet (siehe Nummer stoppen, starten oder entfernen).
• Adressprüfung: Die URL wird vor jeder Anfrage erneut geprüft; an einen Host, der inzwischen auf ein privates Netzwerk zeigt oder sich nicht auflösen lässt, wird nichts gesendet, und diese Nachricht wird nicht wiederholt.

Header#

Signatur prüfen#

Jede Anfrage wird mit dem Webhook-Secret der Nummer per HMAC-SHA256 über den rohen Request-Body genau so, wie er ankommt, signiert. Der Hex-Digest in Kleinbuchstaben wird in X-Wbiztool-Signature als sha256=<digest> gesendet. Ein auf der Seite Posteingangsnummern eingerichteter Webhook hat immer ein Secret, der Header ist also immer vorhanden.

Berechnen Sie die Signatur aus den rohen Bytes, bevor Sie das JSON parsen. Parsen und erneutes Kodieren verändert den Body (Leerzeichen, maskierte Zeichen), und die Signatur stimmt nicht mehr.

// Express: register this route before app.use(express.json()), or the raw body is lost
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 a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  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); // answer 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);

Um Ihren Empfänger zu testen, bevor eine echte Nachricht ankommt, signieren Sie selbst einen Body und senden ihn:

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

Die Signatur deckt den Body ab, einschließlich seines timestamp, der bei jedem Versuch neu ist. Um wiederholt eingespielte Anfragen abzuweisen, lehnen Sie einen timestamp ab, der älter als 5 Minuten ist, und überspringen eine message.id, die Sie schon verarbeitet haben.

Payload#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

Die Nummern, IDs und Namen oben sind Beispiele. Der echte Body ist eine Zeile kompaktes JSON, und jedes Nicht-ASCII-Zeichen (Umlaute und Akzente, andere Schriften, Emoji) kommt als \uXXXX-Escape an, z. B. \ud83d\udcf8 für 📸. Weitere Felder können hinzukommen; ignorieren Sie die, die Sie nicht verwenden.

Felder der obersten Ebene#

Felder von message#

Felder von contact#

Zapier und Posteingangsnummern#

Der WbizTool-Trigger Incoming WhatsApp Message in Zapier nutzt diese Webhooks. Das Einschalten eines Zaps nimmt die Nummer bei Bedarf in den Posteingang auf (sie belegt dann eine Ihrer Posteingangsnummern) und richtet ihren Webhook auf Zapier aus, nur für empfangene Nachrichten und mit eigenem Secret; die Karte zeigt ein Zapier-Badge. Ihre eigene Webhook-URL, Ihr Secret und Ihre Haken kommen zurück, wenn der Zap ausgeschaltet wird.

Webhook-Einstellungen warnt dann: „Dieser Webhook gehört zu einem Zapier-Zap. Wenn Sie die URL ändern oder entfernen, erhält der Zap keine Nachrichten mehr.“ Auch Stoppen und Entfernen warnen: Der Zap bleibt in Zapier eingeschaltet, erhält aber nichts – schalten Sie ihn also stattdessen in Zapier aus. Siehe So arbeitet der Trigger mit Ihren Posteingangsnummern zusammen.

Ohne Unibox-Add-on#

Die Seite zeigt „Kein Unibox-Add-on“ und „Das Unibox-Add-on ist in diesem Arbeitsbereich nicht aktiv.“, und Nummer zum Posteingang hinzufügen öffnet Unibox-Add-on erforderlich: „Um WhatsApp-Nummern zum gemeinsamen Posteingang hinzuzufügen und ihre Nachrichten per Webhook zu erhalten, buchen Sie das Unibox-Add-on.“ Ein Inhaber klickt auf Add-ons ansehen und fügt unter Abrechnung & Pläne das Add-on Unibox-Nummer hinzu, bei einem bezahlten Plan oder Lifetime-Plan (nicht in der kostenlosen Testphase).

Wenn das Add-on endet oder eine Nummer getrennt wird#

• Das Add-on endet: Jede Posteingangsnummer wird gestoppt, sofort oder innerhalb von etwa einer Stunde. Die Karten zeigen Gestoppt mit „Gestoppt, weil das Unibox-Add-on in diesem Arbeitsbereich nicht aktiv ist.“ Inhaber und Bearbeiter erfahren, welche Posteingänge gestoppt wurden, in der Abrechnungs-E-Mail oder in der Benachrichtigung „Einige Nummern oder Funktionen von … wurden gestoppt“ (Nummern- & Versandprobleme unter Benachrichtigungen). Unterhaltungen, Webhook-URLs und Secrets bleiben erhalten: Sobald das Add-on wieder aktiv ist, klicken Sie bei jeder Nummer auf Starten. Nachrichten aus der Zeit, in der sie gestoppt war, kommen dann bis zu 30 Tage zurück in den Posteingang, werden aber nicht an Ihren Webhook gesendet.
• Das Add-on deckt weniger Nummern ab, als eingeschaltet sind: „Es sind mehr Nummern aktiv, als Ihr Add-on erlaubt. Die neuesten zusätzlichen werden innerhalb von etwa einer Stunde automatisch gestoppt.“
• Die Nummer wird getrennt: Die Karte zeigt Nummer getrennt, und nichts wird synchronisiert oder gesendet. Nachdem Sie sie neu verbunden haben, werden die Nachrichten, die in der Zwischenzeit eingegangen sind, ebenfalls abgeholt und gesendet; bei denen, die älter als 10 Minuten sind, steht replayed auf true.
• Sie wird mit einem anderen Telefon neu verbunden: Die Posteingangsnummer und ihr Webhook laufen ab diesem Moment für die neue Nummer weiter (dieselbe whatsapp_client_id, neue whatsapp_phone); die alten Chats bleiben als Verlauf im Posteingang.

Fehlerbehebung#

Verwandte Themen#

• Unibox-Posteingang: die Chats Ihrer Posteingangsnummern lesen und beantworten
• Zapier-Integration
• WhatsApp-Nummer verbinden
• Pläne und Abrechnung
• Nachricht senden (API): Das Feld webhook dieser API meldet, ob eine von Ihnen gesendete Nachricht rausgegangen ist (ein anderer Webhook)