Dokumentation

Eingehende Webhooks

Antworten deiner verbundenen WhatsApp-Nummer in Echtzeit empfangen. Drop-in-kompatibel mit TextMeBot — bestehende Integrationen, die type / from / from_name / to / file / message verarbeiten, funktionieren ohne Anpassungen.

1. Endpoint konfigurieren

Öffne /admin/webhook im Customer Portal:

  1. Füge deine öffentliche HTTPS-URL ein.
  2. Klicke Speichern — ein HMAC-Secret mit 64 Zeichen wird automatisch generiert. Kopiere es sofort, danach wird es maskiert.
  3. Klicke Test fire, um einen Beispiel-Payload an deinen Endpoint zu senden.

2. Payload (TextMeBot-kompatibel)

Bei jeder eingehenden Nachricht macht TextMeFlow einen POST mit Content-Type application/json und diesem Body:

{
  "type": "text",
  "from": "32472932208",
  "from_name": "Jan Janssens",
  "to": "32499123456",
  "file": "null",
  "message": "Bedankt voor de bevestiging!",
  "from_me": false,
  "wa_message_id": "3EB0A1B2C3D4E5F6",
  "message_id": null
}
FeldTypInhalt
typestringtext, image, audio, video, document oder location
fromstringAbsender, nur Ziffern (kein +)
from_namestringWhatsApp pushName, kann leer sein
tostringDeine verbundene Nummer, nur Ziffern
filestringFür Text-Nachrichten wörtlich der String "null" (wie bei TextMeBot). Für image, video, audio und document die URL der Datei, gehostet von TextMeFlow. Ein Foto ohne Bildunterschrift kommt mit leerer message an.
messagestringText oder Bildunterschrift; bei document der Dateiname, bei location der String "lat,lng"
from_mebooleantrue für eine Nachricht, die du gesendet hast — per API oder von Hand in WhatsApp. So sieht dein System das vollständige Gespräch. Bei true ist from deine Nummer und to die des Kunden.
wa_message_idstringDie WhatsApp-ID der Nachricht, in beide Richtungen. Eindeutig pro Nachricht; als Deduplizierungsschlüssel nutzbar.
message_idstring | nullNur bei from_me: true und per API gesendet: die message_id, die du beim Senden erhalten hast. Daran erkennst du deine eigene Sendung und speicherst sie nicht doppelt. null für von Hand getippte Nachrichten und für alles Eingehende.

3. Header

HeaderInhalt
Content-Typeapplication/json
User-AgentTextMeFlow-Webhook/1.0
X-TextMeFlow-Event-IdUUID pro Nachricht — nutze sie als Idempotency-Key, Retries verwenden dieselbe Id.
X-TextMeFlow-Signaturesha256=<hex> — HMAC-SHA256 des Raw-Bodys mit deinem Webhook-Secret.
X-TextMeFlow-DeliveryUUID pro Zustellversuch, praktisch fürs Log-Grepping.

4. Signatur verifizieren

Berechne HMAC-SHA256 über den Raw Request Body (nicht über ein geparstes Objekt — JSON-Encoder-Unterschiede brechen sonst deinen Hash) und vergleiche constant-time mit dem sha256=…-Wert aus dem Header.

PHP

// $secret = 'tmf_…' uit /admin/webhook
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$received = $_SERVER['HTTP_X_TEXTMEFLOW_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
$body = json_decode($raw, true);

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// Capture raw body for HMAC; can't run after express.json() ate it.
app.use(express.raw({ type: 'application/json' }));

app.post('/textmeflow-inbound', (req, res) => {
  const raw = req.body; // Buffer
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.TMF_WEBHOOK_SECRET)
    .update(raw)
    .digest('hex');

  const received = req.get('X-TextMeFlow-Signature') ?? '';
  if (
    expected.length !== received.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  ) {
    return res.sendStatus(401);
  }

  const body = JSON.parse(raw.toString('utf8'));
  // …handle body…
  res.sendStatus(200);
});

Python (Flask)

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['TMF_WEBHOOK_SECRET'].encode()

@app.post('/textmeflow-inbound')
def inbound():
    raw = request.get_data()
    expected = 'sha256=' + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get('X-TextMeFlow-Signature', '')
    if not hmac.compare_digest(expected, received):
        abort(401)
    body = request.get_json()
    # …handle body…
    return '', 200

5. Retry-Policy

Eine Zustellung ist erfolgreich bei jeder 2xx-Response innerhalb von 10 s. Andere Ergebnisse:

ResponseVerhalten
2xx zugestellt, kein Retry.
408 / 429 / 5xx Retry — max. 5-mal mit Backoff 1m, 5m, 30m, 2h, 6h.
andere 4xx fehlgeschlagen, kein Retry. Ein 401 bedeutet meist, dass dein Secret nicht mehr passt — prüfe und korrigiere auf deiner Seite.
Timeout / Netzwerk Retry wie bei 5xx.

Nach insgesamt 6 Versuchen (erster + 5 Retries) wird die Zustellung als failed markiert. Den Status jedes Versuchs siehst du in /admin/webhook.

6. Migration von TextMeBot

Keine Code-Änderungen nötig — die Payload-Form ist identisch. Eine Aktion:

  1. Füge deine bestehende TextMeBot-Endpoint-URL in /admin/webhook ein.
  2. Füge einen Signatur-Check hinzu (TextMeBot hat keinen — Pflicht-Upgrade für die Produktion). Siehe die Snippets oben.

Bereit zum Empfangen?

Konfiguriere deinen Endpoint in /admin/webhook und sende einen Test-Payload mit einem Klick.