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:

  1. Paste your public HTTPS URL.
  2. Click Save — a 64-char HMAC secret is generated automatically. Copy it right away, it will be masked afterwards.
  3. 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
}
FieldTypeContent
typestringtext, image, audio, video, document or location
fromstringSender, digits only (no +)
from_namestringWhatsApp pushName, may be empty
tostringYour linked number, digits only
filestringFor 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.
messagestringText or caption; for document the filename, for location the string "lat,lng"
from_mebooleantrue 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_idstringThe WhatsApp id of the message, in both directions. Unique per message; usable as a deduplication key.
message_idstring | nullOnly 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

HeaderContent
Content-Typeapplication/json
User-AgentTextMeFlow-Webhook/1.0
X-TextMeFlow-Event-IdUUID per message — use this as an idempotency key, retries reuse the same id.
X-TextMeFlow-Signaturesha256=<hex> — HMAC-SHA256 of the raw body with your webhook secret.
X-TextMeFlow-DeliveryUUID 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:

ResponseBehaviour
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:

  1. Paste your existing TextMeBot endpoint URL into /admin/webhook.
  2. 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.