Webhooks do ZapFácil
Webhooks permitem receber notificações estruturadas em tempo real em seu servidor sempre que um evento relevante ocorrer no WhatsApp. As requisições são enviadas como chamadas HTTP POST para a URL que você configurou no Painel de Controle.
🛡️ Verificação de Assinatura (HMAC-SHA256):
Se você configurou um webhook_secret em seu painel, toda requisição de webhook incluirá o cabeçalho X-ZapFacil-Signature: sha256={hash}. Valide o payload calculando o HMAC-SHA256 do corpo cru da requisição para comprovar a legitimidade da origem.
Validação HMAC
Abaixo estão exemplos práticos de como validar a assinatura HMAC enviada no cabeçalho X-ZapFacil-Signature no seu backend:
Exemplo em Node.js
import crypto from "node:crypto";
function verifyWebhookSignature(payloadRawBody, signatureHeader, secret) {
const hmac = crypto.createHmac("sha256", secret);
const digest = "sha256=" + hmac.update(payloadRawBody).digest("hex");
return crypto.timingSafeEqual(
Buffer.from(digest),
Buffer.from(signatureHeader)
);
}Exemplo em PHP
function verifyWebhookSignature($payloadRawBody, $signatureHeader, $secret) {
$expected = 'sha256=' . hash_hmac('sha256', $payloadRawBody, $secret);
return hash_equals($expected, $signatureHeader);
}Disparado em tempo real sempre que um novo chat, mensagem de texto ou de áudio/voz é recebida pelo celular emparelhado.
Payload Exemplo (Texto)
{
"event": "MESSAGE_RECEIVED",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b",
"timestamp": "2026-06-08T21:27:23Z",
"data": {
"phone": "5511999999999",
"message": "Salve",
"message_id": "3EB01B2C3D4E5F6A7B8C9D",
"chat_jid": "299876543210987",
"sender_jid": "299876543210987:99",
"is_group": false,
"is_from_me": false,
"timestamp": "2026-06-08T21:27:23Z",
"type": "text",
"event": "MESSAGE_RECEIVED",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b"
}
}Payload Exemplo (Áudio/Voz)
{
"event": "MESSAGE_RECEIVED",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b",
"timestamp": "2026-06-08T21:27:30Z",
"data": {
"phone": "5511999999999",
"message_id": "3EB01B2C3D4E5F6A7B8C9E",
"chat_jid": "299876543210987",
"sender_jid": "299876543210987:99",
"is_group": false,
"is_from_me": false,
"timestamp": "2026-06-08T21:27:30Z",
"type": "audio",
"audio_base64": "UklGRiS9AABXQVZFZm10IBIA...",
"ptt": true,
"mimetype": "audio/ogg; codecs=opus",
"event": "MESSAGE_RECEIVED",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b"
}
}Estrutura do Payload
application/jsonSempre MESSAGE_RECEIVED.
Identificador único da instância que recebeu a mensagem.
Data e hora do recebimento no formato ISO 8601.
Objeto contendo os dados da mensagem.
Atributos do Objeto
Número do remetente (inclui DDI e DDD).
Conteúdo textual recebido (nulo se for mensagem apenas de mídia/áudio).
Identificador único da mensagem no WhatsApp.
JID do chat de recebimento da mensagem no WhatsApp.
JID do remetente específico da mensagem.
Indica se a mensagem é proveniente de um grupo.
Indica se a mensagem foi enviada por você (pela conta conectada).
Nome público de exibição do remetente no WhatsApp.
Data e hora do recebimento no formato ISO 8601.
Tipo da mensagem (ex: "text" ou "audio").
Evento redundante incluído no objeto de dados.
UUIDv7 da instância incluída no objeto de dados.
Áudio codificado em Base64 (presente se a mensagem for áudio/voz).
Se true, indica que é mensagem de voz gravada na hora (Push-to-Talk).
Tipo MIME do áudio (ex: "audio/ogg; codecs=opus").
Disparado sempre que o estado da sessão do WhatsApp de uma instância é alterado (conecta ou desconecta da plataforma).
Exemplo Conectado
{
"event": "CONNECTION_STATUS",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b",
"timestamp": "2026-06-07T03:01:20Z",
"data": {
"status": "CONNECTED",
"phone": "5511999999999"
}
}Exemplo Desconectado
{
"event": "CONNECTION_STATUS",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b",
"timestamp": "2026-06-07T03:02:15Z",
"data": {
"status": "DISCONNECTED",
"reason": "logout"
}
}Estrutura do Payload
application/jsonSempre CONNECTION_STATUS.
Identificador único da Instância.
Data e hora do evento no formato ISO 8601.
Objeto contendo as informações de status.
Atributos do Objeto
Novo estado da instância ("CONNECTED" ou "DISCONNECTED").
Número de celular emparelhado. Presente apenas em status "CONNECTED".
Motivo da desconexão (ex: "logout"). Presente apenas em status "DISCONNECTED".
Disparado assim que a conexão é iniciada e um novo código QR fica disponível para leitura e sincronização de conta.
Exemplo de Resposta
{
"event": "QR_CODE",
"instance_id": "019002a2-3f1d-7201-9a74-b528a7f5b12b",
"timestamp": "2026-06-07T03:00:05Z",
"data": {
"qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAA...",
"qr_code_raw": "[email protected]_code"
}
}Estrutura do Payload
application/jsonSempre QR_CODE.
Identificador único da Instância.
Data e hora do evento no formato ISO 8601.
Objeto contendo as chaves do QR Code.
Atributos do Objeto
String de imagem no formato Base64 (ideal para renderizar imagens em tags <img>).
Texto cru do QR Code (ideal para gerar QR Codes sob demanda no seu frontend).