Guia de integração

🧾 Lista de Eventos Disponíveis

`instance.qrcode.generated`

Emitido quando um novo QR Code é gerado para autenticação da instância.

Payload de exemplo:

{
  "id": "437814524293287936",
  "event": "instance.qrcode.generated",
  "timestamp": "2025-04-23T03:18:36.792Z",
  "data": {
    "accountId": "420339940270936064",
    "instanceId": "420644313987420160",
    "status": "DISCONNECTED",
    "base64QrCode": "data:image/png;base64,..."
  }
}

`instance.connected`

Indica que a instância foi conectada com sucesso e está pronta para enviar e receber mensagens.

Payload de exemplo:

{
  "id": "437814329547558912",
  "event": "instance.connected",
  "timestamp": "2025-04-23T03:17:50.361Z",
  "data": {
    "accountId": "420339940270936064",
    "instanceId": "420644313987420160",
    "status": "CONNECTED"
  }
}

`instance.disconnected`

Notifica que a instância perdeu a conexão. Não será possível enviar ou receber mensagens até a reconexão.

Payload de exemplo:

{
  "id": "437837906921525248",
  "event": "instance.disconnected",
  "timestamp": "2025-04-23T04:51:31.646Z",
  "data": {
    "accountId": "420339940270936064",
    "instanceId": "420644313987420160",
    "status": "DISCONNECTED"
  }
}

`message.received`

Notifica o recebimento de uma nova mensagem do WhatsApp, incluindo mensagens de mídia.

Payload de exemplo (resumido):

{
  "id": "437830800709390336",
  "event": "message.received",
  "timestamp": "2025-04-23T04:23:17.392Z",
  "data": {
    "id": "...",
    "body": "...",
    "type": "image",
    "caption": "Mensagem com mídia",
    "from": "120363049016113262@g.us",
    "to": "5511949981269@c.us",
    "author": "553182306332@c.us",
    ...
  }
}

🔒 Segurança e Assinatura de Requisições

Para garantir a autenticidade dos dados recebidos via webhook, cada requisição enviada pela plataforma pode ser assinada com um header criptográfico. Isso permite que o receptor valide se a mensagem foi modificada ou interceptada.

Header de Assinatura (recomendado)

Header:

X-Signature: <hash>

Geração do hash (HMAC SHA-256):

hash = HMAC-SHA256(secret, raw_body)

secret: Chave privada compartilhada (fornecida previamente via painel ou API).

raw_body: Corpo bruto da requisição, exatamente como recebido antes de qualquer parsing.

Como validar:

Leia o corpo da requisição como texto bruto (sem parse).

Calcule o HMAC SHA256 usando o corpo e o secret.

Compare com o valor enviado no header X-Signature.

🔁 Retentativas e Redeliveries

Em caso de falha na entrega (ex: resposta HTTP 4xx ou 5xx), o sistema pode realizar reentregas com backoff exponencial. Certifique-se de responder com HTTP 2xx para confirmar o recebimento com sucesso.

✅ Boas práticas

Valide a assinatura em todas as requisições.

Use HTTPS para proteger a comunicação.

Implemente logs para auditoria de eventos recebidos.

Armazene event.id para evitar processamento duplicado.

Guia de integração

🧾 Lista de Eventos Disponíveis#

instance.qrcode.generated#

instance.connected#

instance.disconnected#

message.received#

🔒 Segurança e Assinatura de Requisições#

Header de Assinatura (recomendado)#

🔁 Retentativas e Redeliveries#

✅ Boas práticas#

🧾 Lista de Eventos Disponíveis

`instance.qrcode.generated`

`instance.connected`

`instance.disconnected`

`message.received`

🔒 Segurança e Assinatura de Requisições

Header de Assinatura (recomendado)

🔁 Retentativas e Redeliveries

✅ Boas práticas