Documentation
Inbound webhooks
Receive replies from your linked WhatsApp number in realtime. Drop-in compatible with TextMeBot — existing integrations that process type / from / from_name / to / file / message keep working without changes.
1. Configure your endpoint
Open /admin/webhook in the customer portal:
- Paste your public HTTPS URL.
- Click Save — a 64-char HMAC secret is generated automatically. Copy it right away, it will be masked afterwards.
- Click Test fire to send a sample payload to your endpoint.
2. Payload (TextMeBot-compatible)
For every inbound message TextMeFlow makes a POST with content-type application/json and this 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
}
| Field | Type | Content |
|---|---|---|
| type | string | text, image, audio, video, document or location |
| from | string | Sender, digits only (no +) |
| from_name | string | WhatsApp pushName, may be empty |
| to | string | Your linked number, digits only |
| file | string | For text messages literally the string "null" (matches TextMeBot). For image, video, audio and document the URL of the file, hosted by TextMeFlow. A photo without a caption arrives with an empty message. |
| message | string | Text or caption; for document the filename, for location the string "lat,lng" |
| from_me | boolean | true for a message you sent — via the API or by hand in WhatsApp. That way your own system sees the full conversation. When true, from is your number and to the customer's. |
| wa_message_id | string | The WhatsApp id of the message, in both directions. Unique per message; usable as a deduplication key. |
| message_id | string | null | Only with from_me: true and sent via the API: the message_id you received when sending. That is how you recognise your own send and avoid storing it twice. null for hand-typed messages and for everything incoming. |
3. Headers
| Header | Content |
|---|---|
| Content-Type | application/json |
| User-Agent | TextMeFlow-Webhook/1.0 |
| X-TextMeFlow-Event-Id | UUID per message — use this as an idempotency key, retries reuse the same id. |
| X-TextMeFlow-Signature | sha256=<hex> — HMAC-SHA256 of the raw body with your webhook secret. |
| X-TextMeFlow-Delivery | UUID per delivery attempt, handy for log grepping. |
4. Verify the signature
Compute HMAC-SHA256 over the raw request body (not over a parsed object — JSON encoder differences will break your hash otherwise) and compare constant-time with the sha256=… value from the 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
A delivery is successful on any 2xx response within 10s. Other outcomes:
| Response | Behaviour |
|---|---|
| 2xx | delivered, no retry. |
| 408 / 429 / 5xx |
retry — max 5 times with backoff 1m, 5m, 30m, 2h, 6h. |
| other 4xx |
failed, no retry. A 401 usually means your secret no longer matches — check and fix on your side. |
| timeout / network | retry like 5xx. |
After 6 total attempts (first + 5 retries) the delivery is marked as failed. You can see the status of every attempt in /admin/webhook.
6. Migrating from TextMeBot
No code changes needed — the payload shape is identical. One action:
- Paste your existing TextMeBot endpoint URL into /admin/webhook.
- Add a signature check (TextMeBot doesn't have one — a mandatory upgrade for production). See the snippets above.
Ready to receive?
Configure your endpoint in /admin/webhook and send a test payload with one click.