TWMULT Docs

Webhooks

Webhooks avisam o seu sistema quando algo acontece no TWMULT: mensagem recebida, pedido criado, pagamento confirmado e mais. Cada evento chega como um POST JSON assinado.

Cadastrar um webhook

  1. Abra Conta → Integrações → Webhooks e clique em Novo webhook.
  2. Informe a URL de destino, que precisa ser pública (de preferência https), e marque os eventos desejados. Se nenhum for marcado, o webhook recebe todos.
  3. Copie o secret exibido. Ele é usado para verificar a assinatura.
  4. Use o botão Testar para enviar um evento ping e confirmar que o seu endpoint responde.

Formato

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-TWMULT-Event: message.received
X-TWMULT-Timestamp: 1794859200
X-TWMULT-Signature: sha256=5d41402abc4b2a76b9719d911017c592...

{
  "id": "evt_...",
  "event": "message.received",
  "createdAt": "2026-11-16T20:00:00.000Z",
  "data": {
    "phone": "5583999991234",
    "name": "Ana",
    "text": "Quero comprar",
    "type": "text",
    "conversationId": "..."
  }
}
CabeçalhoConteúdo
X-TWMULT-EventNome do evento, igual ao campo event.
X-TWMULT-TimestampMomento do envio, em segundos desde 1970 (Unix).
X-TWMULT-Signaturesha256=<hex>: assinatura HMAC-SHA256 do envio.

Eventos

EventoQuandoCampos em data
message.receivedCliente enviou mensagemphone, name, text, type, conversationId, instanceId
message.sentMensagem enviada pelo painel, bot ou APIphone, text, type, conversationId, fromBot
contact.createdContato novoid, phone, name
order.createdPedido feito pelo bot de catálogonumber, totalCents, items, phone, pixCode
order.paidPedido marcado como pagonumber, totalCents, phone
conversation.closedAtendimento encerradoconversationId, phone
campaign.completedCampanha terminouid, name, total, sent, failed
instance.statusConexão mudou de estadoid, name, status, phone
pingBotão “Testar”{}

Entrega e reenvio

O status e o erro da última entrega aparecem na lista de webhooks do painel.

Verificar a assinatura

A assinatura é o HMAC-SHA256 de timestamp + "." + corpo, calculado com o secret do webhook e codificado em hexadecimal:

assinatura = "sha256=" + hex(HMAC_SHA256(secret, X-TWMULT-Timestamp + "." + corpo_bruto))

Para verificar:

  1. Leia o corpo bruto da requisição, exatamente como chegou. Não reserialize o JSON: qualquer espaço diferente muda a assinatura.
  2. Calcule a assinatura esperada com o X-TWMULT-Timestamp recebido.
  3. Compare com X-TWMULT-Signature usando uma comparação de tempo constante.
  4. Recomendado: rejeite eventos com timestamp de mais de 5 minutos, para evitar reenvio malicioso.

Node.js (Express)

const crypto = require("crypto");
const express = require("express");

const app = express();
const secret = process.env.TWMULT_WEBHOOK_SECRET;

// express.raw mantém o corpo bruto, necessário para a assinatura.
app.post("/webhooks/twmult", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("X-TWMULT-Timestamp") || "";
  const signature = req.get("X-TWMULT-Signature") || "";
  const rawBody = req.body.toString("utf8");

  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;

  if (!valid || !fresh) return res.sendStatus(401);

  const event = JSON.parse(rawBody);
  if (event.event === "message.received") {
    console.log(`Mensagem de ${event.data.phone}: ${event.data.text}`);
  }
  res.sendStatus(200);
});

app.listen(3000);

Python (Flask)

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["TWMULT_WEBHOOK_SECRET"].encode()


@app.post("/webhooks/twmult")
def twmult_webhook():
    ts = request.headers.get("X-TWMULT-Timestamp", "")
    signature = request.headers.get("X-TWMULT-Signature", "")
    raw_body = request.get_data()  # bytes, exatamente como chegaram

    digest = hmac.new(SECRET, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    expected = "sha256=" + digest
    if not hmac.compare_digest(signature, expected):
        abort(401)
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(401)

    event = request.get_json()
    if event["event"] == "order.paid":
        print("Pedido pago:", event["data"]["number"])
    return "", 200

PHP

<?php
$secret = getenv('TWMULT_WEBHOOK_SECRET');

$ts = $_SERVER['HTTP_X_TWMULT_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_TWMULT_SIGNATURE'] ?? '';
$rawBody = file_get_contents('php://input');

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);

if (!hash_equals($expected, $signature) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
if ($event['event'] === 'order.created') {
    error_log('Novo pedido #' . $event['data']['number'] . ' — Pix: ' . $event['data']['pixCode']);
}

http_response_code(200);

Dicas para testar