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:
- Füge deine öffentliche HTTPS-URL ein.
- Klicke Speichern — ein HMAC-Secret mit 64 Zeichen wird automatisch generiert. Kopiere es sofort, danach wird es maskiert.
- 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
}
| Feld | Typ | Inhalt |
|---|---|---|
| type | string | text, image, audio, video, document oder location |
| from | string | Absender, nur Ziffern (kein +) |
| from_name | string | WhatsApp pushName, kann leer sein |
| to | string | Deine verbundene Nummer, nur Ziffern |
| file | string | Fü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. |
| message | string | Text oder Bildunterschrift; bei document der Dateiname, bei location der String "lat,lng" |
| from_me | boolean | true 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_id | string | Die WhatsApp-ID der Nachricht, in beide Richtungen. Eindeutig pro Nachricht; als Deduplizierungsschlüssel nutzbar. |
| message_id | string | null | Nur 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
| Header | Inhalt |
|---|---|
| Content-Type | application/json |
| User-Agent | TextMeFlow-Webhook/1.0 |
| X-TextMeFlow-Event-Id | UUID pro Nachricht — nutze sie als Idempotency-Key, Retries verwenden dieselbe Id. |
| X-TextMeFlow-Signature | sha256=<hex> — HMAC-SHA256 des Raw-Bodys mit deinem Webhook-Secret. |
| X-TextMeFlow-Delivery | UUID 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:
| Response | Verhalten |
|---|---|
| 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:
- Füge deine bestehende TextMeBot-Endpoint-URL in /admin/webhook ein.
- 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.