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
- Abra Conta → Integrações → Webhooks e clique em Novo webhook.
- 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.
- Copie o secret exibido. Ele é usado para verificar a assinatura.
- Use o botão Testar para enviar um evento
pinge 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çalho | Conteúdo |
|---|---|
X-TWMULT-Event | Nome do evento, igual ao campo event. |
X-TWMULT-Timestamp | Momento do envio, em segundos desde 1970 (Unix). |
X-TWMULT-Signature | sha256=<hex>: assinatura HMAC-SHA256 do envio. |
Eventos
| Evento | Quando | Campos em data |
|---|---|---|
message.received | Cliente enviou mensagem | phone, name, text, type, conversationId, instanceId |
message.sent | Mensagem enviada pelo painel, bot ou API | phone, text, type, conversationId, fromBot |
contact.created | Contato novo | id, phone, name |
order.created | Pedido feito pelo bot de catálogo | number, totalCents, items, phone, pixCode |
order.paid | Pedido marcado como pago | number, totalCents, phone |
conversation.closed | Atendimento encerrado | conversationId, phone |
campaign.completed | Campanha terminou | id, name, total, sent, failed |
instance.status | Conexão mudou de estado | id, name, status, phone |
ping | Botão “Testar” | {} |
Entrega e reenvio
- Responda com qualquer status
2xxem até 10 segundos. - Se a resposta demorar ou vier com outro status, o evento é reenviado até 5 vezes, com espera crescente entre as tentativas.
- Como um evento pode chegar mais de uma vez, use o campo
idpara ignorar duplicatas. - Responda rápido e processe o trabalho pesado depois, numa fila do seu lado.
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:
- Leia o corpo bruto da requisição, exatamente como chegou. Não reserialize o JSON: qualquer espaço diferente muda a assinatura.
- Calcule a assinatura esperada com o
X-TWMULT-Timestamprecebido. - Compare com
X-TWMULT-Signatureusando uma comparação de tempo constante. - 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
- Use o botão Testar para receber um
pinge conferir a verificação da assinatura. - Durante o desenvolvimento, um túnel como ngrok ou um serviço de inspeção de requisições ajuda a ver o corpo exato que chega.
- No n8n, Make e Zapier, use um gatilho de webhook. Se a ferramenta não deixar verificar a assinatura, pelo menos mantenha a URL secreta.