Skip to navigation
Conceitos

Webhooks

Visão geral

Webhooks permitem que o Muchaw DEV envie notificações de eventos em tempo real para o seu servidor. Quando uma mensagem é recebida, um status de entrega muda ou um número é ativado, o Muchaw DEV envia uma requisição HTTP POST para as suas URLs de webhook configuradas.

Esta página cobre seus webhooks — as URLs que o Muchaw DEV chama no seu servidor. Isso é separado do webhook interno da Meta que o Muchaw DEV usa para receber eventos da Meta.

Eventos disponíveis

EventoDisparado quando
message.receivedUma mensagem WhatsApp recebida chega
message.sentUma mensagem é aceita pelos servidores da Meta
message.deliveredUma mensagem é entregue ao dispositivo do destinatário
message.readUma mensagem é lida pelo destinatário
message.failedUma entrega de mensagem falha
number.activatedUm número de WhatsApp conclui o provisionamento e está pronto
number.disconnectedUm número é desconectado
number.bannedUm número é banido pela Meta

Criando um webhook

curl -X POST https://dev.muchau.com.br/api/webhooks \
  -H "Authorization: Bearer $MUCHAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-servidor.com/webhooks/muchaw",
    "events": ["message.received", "number.activated"]
  }'

Resposta (salve o secret — ele é exibido apenas uma vez):

{
  "id": "wh_01j...",
  "url": "https://seu-servidor.com/webhooks/muchaw",
  "secret": "whsec_...",
  "events": ["message.received", "number.activated"],
  "numberIds": [],
  "active": true,
  "createdAt": "2024-01-15T10:00:00.000Z"
}

Filtrar por número

Para receber eventos apenas de números específicos, passe numberIds:

{
  "url": "https://seu-servidor.com/webhooks/muchaw",
  "events": ["message.received"],
  "numberIds": ["clxyz123..."]
}

Verificando assinaturas de webhook

Cada requisição de webhook do Muchaw DEV inclui um header X-Muchaw-Signature com uma assinatura HMAC-SHA256.

Sempre verifique esta assinatura antes de processar o evento.

import crypto from "node:crypto";
function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}
// Exemplo com Express
app.post("/webhooks/muchaw", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-muchaw-signature"];
  if (!verifySignature(req.body, sig, process.env.MUCHAW_WEBHOOK_SECRET)) {
    return res.status(401).send("Assinatura inválida");
  }
  const event = JSON.parse(req.body.toString());
  // processar evento...
  res.sendStatus(200);
});

Estrutura do payload de webhook

{
  "event": "message.received",
  "timestamp": "2024-01-15T10:05:00.000Z",
  "data": {
    "id": "msg_01j...",
    "numberId": "clxyz123...",
    "direction": "INBOUND",
    "fromNumber": "5511888880000",
    "toNumber": "5511999990000",
    "type": "text",
    "body": { "body": "Olá!" },
    "createdAt": "2024-01-15T10:05:00.000Z"
  }
}

Política de retry

Se o seu servidor retornar uma resposta não-2xx ou atingir o timeout, o Muchaw DEV tenta novamente com backoff exponencial:

TentativaIntervalo
1ª retry~30 segundos
2ª retry~5 minutos
3ª retry~30 minutos

Após 3 tentativas com falha, o evento é descartado. Se um webhook acumular 10 falhas consecutivas, ele é desativado automaticamente.

Rotacionando o secret

curl -X POST https://dev.muchau.com.br/api/webhooks/<id>/rotate-secret \
  -H "Authorization: Bearer $MUCHAW_API_KEY"

Atualize o secret na configuração do seu servidor antes que o antigo expire.