Mandapi/ Documentação
Ir para o painel

Webhooks

Receba eventos em tempo real na sua URL. Você pode configurar o webhook pela API (abaixo) ou pelo painel.

Gere uma chave em Painel → API Keys. A chave fica só no seu navegador (localStorage) e nunca aparece nos exemplos de código.

Listar webhooks

GET/v1/settings/webhooks

Lista os webhooks configurados para a sua conta.

Resposta 200

[
  {
    "id": "665f…",
    "channelId": null,
    "url": "https://sua-app.com/webhooks/mandapi",
    "events": [
      "messages",
      "statuses"
    ],
    "secret": "whsec_…",
    "active": true,
    "failureCount": 0,
    "lastDeliveryAt": null,
    "lastError": null,
    "createdAt": "2026-07-22T18:00:00Z"
  }
]
curl -X GET "https://api.mandapi.net/v1/settings/webhooks" \
  -H "Authorization: Bearer mapi_live_SUA_CHAVE"
▶ Testar no sandbox

Definir webhook

PUT/v1/settings/webhooks

Cria/atualiza (idempotente) o webhook do canal vinculado à chave. Cada entrega é assinada com HMAC-SHA256 no header X-Mandapi-Signature.

CampoTipoDescrição
urlobrigatóriostringURL https que receberá os eventos.
eventsstring[]messages, statuses, reactions, groups, channels.

Resposta 200

{
  "id": "665f…",
  "url": "https://sua-app.com/webhooks/mandapi",
  "events": [
    "messages",
    "statuses"
  ],
  "secret": "whsec_…",
  "active": true
}
curl -X PUT "https://api.mandapi.net/v1/settings/webhooks" \
  -H "Authorization: Bearer mapi_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://sua-app.com/webhooks/mandapi",
  "events": [
    "messages",
    "statuses"
  ]
}'
▶ Testar no sandbox

Eventos de saída

Quando algo acontece, o Mandapi faz um POST para a sua URL. Tipos emitidos hoje:

  • • messages — mensagem recebida
  • • statuses — entrega/leitura de uma mensagem enviada
  • • channels — mudança de estado do canal (conectado/desconectado)

Assinatura (HMAC-SHA256)

Cada entrega vai com o header X-Mandapi-Signature: sha256=<hex>, calculado com o segredo do webhook (whsec_…) sobre o corpo bruto. Valide antes de confiar no evento:

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Exemplo de corpo

{
  "event": "messages",
  "channelId": "665e…",
  "timestamp": "2026-07-22T18:00:00Z",
  "data": {
    "id": "3EB0…",
    "from": "5511999998888@s.whatsapp.net",
    "type": "text",
    "body": "Oi!"
  }
}