Inbound Message Webhook

Trigger

Fired once for every inbound message received on any of your numbers, including replies to team-member sends. Opt-out replies (STOP, UNSUBSCRIBE, etc.) still fire the webhook — is_optout tells you which they were, and the opt-out has already been recorded on your account.

Request

Headers

Body

message_id is the stable identifier for the inbound message — use it as your idempotency key so duplicate deliveries (network hiccups, retries) don't double-process.

{
  "event": "message.inbound",
  "message_id": "8c1f9b2e-1a4c-4f87-9bd2-2d2f6f6f6f6f",
  "from": "+61412345678",
  "to": "+61480123456",
  "body": "STOP",
  "received_at": "2026-05-06T03:14:25.421Z",
  "in_reply_to": "1d4e9b2e-1a4c-4f87-9bd2-2d2f6f6f6f6f",
  "is_optout": true
}

Verifying the signature (Node.js)

Always verify the signature before trusting the payload. Use the raw request bytes (not a re-serialised JSON string) and a constant-time comparison.

import crypto from "node:crypto";

app.post("/webhooks/texto-inbound", express.raw({ type: "application/json" }), (req, res) => {
  const signatureHeader = req.header("x-texto-signature") || "";
  const expected = crypto
    .createHmac("sha256", process.env.TEXTO_INBOUND_WEBHOOK_SECRET)
    .update(req.body) // raw bytes — not JSON.stringify(parsed)
    .digest("hex");

  const provided = signatureHeader.replace(/^sha256=/, "");

  const ok =
    provided.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(provided, "hex"), Buffer.from(expected, "hex"));

  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  // Dedupe on event.message_id (stable across retries)
  res.sendStatus(200);
});

Retry schedule

Up to 3 attempts in total — same schedule as delivery receipts. Reply with any 2xx within 15 seconds to acknowledge.