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.

Eventos disponíveis

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

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

Filtrar por número

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

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

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.

1
import crypto from "node:crypto";
2
3
function verifySignature(rawBody, signature, secret) {
4
  const expected = crypto
5
    .createHmac("sha256", secret)
6
    .update(rawBody)
7
    .digest("hex");
8
  return crypto.timingSafeEqual(
9
    Buffer.from(signature),
10
    Buffer.from(`sha256=${expected}`)
11
  );
12
}
13
14
// Exemplo com Express
15
app.post("/webhooks/muchaw", express.raw({ type: "application/json" }), (req, res) => {
16
  const sig = req.headers["x-muchaw-signature"];
17
  if (!verifySignature(req.body, sig, process.env.MUCHAW_WEBHOOK_SECRET)) {
18
    return res.status(401).send("Assinatura inválida");
19
  }
20
  const event = JSON.parse(req.body.toString());
21
  // processar evento...
22
  res.sendStatus(200);
23
});

Estrutura do payload de webhook

1
{
2
  "event": "message.received",
3
  "timestamp": "2024-01-15T10:05:00.000Z",
4
  "data": {
5
    "id": "msg_01j...",
6
    "numberId": "clxyz123...",
7
    "direction": "INBOUND",
8
    "fromNumber": "5511888880000",
9
    "toNumber": "5511999990000",
10
    "type": "text",
11
    "body": { "body": "Olá!" },
12
    "createdAt": "2024-01-15T10:05:00.000Z"
13
  }
14
}

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:

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.