Pular para o conteúdo
apiwpp
Recurso

Webhooks assinados com HMAC e novas tentativas

Receba mensagens, entregas e mudanças de conexão do WhatsApp no seu servidor, com assinatura HMAC-SHA256, 6 tentativas e reenvio de entregas.

Atualizado em

Enviar é metade da integração. A outra metade é saber o que aconteceu depois: se a mensagem foi entregue, se o cliente respondeu, se o número desconectou. Na apiwpp tudo isso chega por webhook: a cada evento, a API faz um POST para o endereço que você configurou no projeto, com um corpo JSON no mesmo formato para todos os tipos de evento.

Você não precisa consultar a API de tempos em tempos para descobrir novidades. O seu servidor recebe o evento, confere a assinatura, responde rápido e processa o conteúdo no seu ritmo.

Como a entrega funciona

Cada projeto tem um endereço de webhook: uma URL https pública que responde direto, sem redirecionamentos. Todos os números conectados ao projeto enviam os eventos para esse endereço, e o campo connectionId diz de qual número veio cada um. Se você usa um projeto por cliente ou por sistema, cada um recebe só os próprios eventos.

Todo evento chega no mesmo envelope, e o conteúdo de data depende do type:

{
  "type": "message.delivery",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-09-25T12:00:02.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "clientRef": "pedido-1234",
    "phone": "+5511988887777"
  }
}

O externalId é o identificador do seu sistema que você associou à conexão (o id do cliente, por exemplo), útil para saber a quem o evento pertence. Sempre que o telefone é conhecido, os eventos trazem jid e phone no formato internacional.

Os eventos

EventoQuando chega
connection.statusA conexão abriu ou fechou, com o motivo e se a API vai reconectar sozinha
message.incomingAlguém escreveu para o número: texto, mídia ou localização, em conversa individual ou em grupo
message.outgoingO número enviou uma mensagem, pela API ou pelo celular; opcional, ativado por projeto
message.deliveryUma mensagem enviada mudou de status: enviada, entregue, lida ou falhou
message.send_failedUm envio com clientRef não vai acontecer, com o motivo
message.reactionAlguém reagiu a uma mensagem ou removeu a reação
contact.resolvedUm remetente que chegou só com LID agora tem telefone
group.joined, group.left, group.updatedO número entrou num grupo, saiu dele ou o grupo mudou

Mídia recebida chega como uma URL assinada e temporária. Baixe o arquivo quando o evento chegar, em vez de guardar a URL, e trate o endereço como um segredo.

O contrato só cresce: tipos e campos novos podem aparecer, mas nada é renomeado nem removido. Por isso, ignore os tipos que você não conhece em vez de responder com erro.

Assinatura HMAC em cada entrega

Com um segredo configurado no projeto, cada tentativa de entrega traz dois cabeçalhos: X-Sales-Timestamp, com os segundos unix do momento do envio, e X-Sales-Signature, com sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto. Verificar os dois garante que o evento veio da apiwpp e que ninguém alterou o conteúdo no caminho. O segredo é do projeto: cada projeto tem o seu, então um cliente da sua agência nunca consegue assinar eventos de outro.

Para aceitar um evento, leia o corpo exatamente como chegou, rejeite um timestamp a mais de 300 segundos do seu relógio e compare a assinatura em tempo constante:

import { createHmac, timingSafeEqual } from 'node:crypto'

function isSigned(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const mac = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex')
  const expected = Buffer.from(`sha256=${mac}`)
  const received = Buffer.from(signature)
  return expected.length === received.length && timingSafeEqual(expected, received)
}

Em PHP, a mesma conta é hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret), comparada com hash_equals. A documentação traz o exemplo completo em Node.js e em PHP.

Nunca verifique com um segredo vazio: se a variável de ambiente não chegou ao processo, recuse todas as entregas até configurá-la.

Novas tentativas e registro de entregas

Responda com um status 2xx em até 10 segundos e deixe o trabalho pesado para depois, numa fila do seu sistema. Qualquer outra resposta, um erro de rede ou o tempo esgotado conta como falha.

Uma entrega que falhou é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: são 6 tentativas no total. Se o seu endpoint falha em sequência, a API pausa as entregas do projeto por alguns minutos e os eventos esperam na fila, sem se perder. Um evento que passa 24 horas sem ser entregue fica marcado como dead.

Cada entrega fica registrada com o estado, o status HTTP e a latência.

Cada entrega fica registrada com o estado, o status HTTP que o seu servidor respondeu, o erro e a latência. Consulte esse histórico no painel ou pela API e, quando o seu endpoint voltar, reenvie pela API uma entrega específica ou todas as que ficaram dead, até 1000 por chamada.

Processe cada evento uma vez só

A entrega é pelo menos uma vez: se o seu servidor processou o evento mas a resposta se perdeu, ele chega de novo. Guarde o messageId (ou a combinação de tipo e identificador) dos eventos já processados e ignore os repetidos. Do lado do envio, use o clientRef: ele volta em message.outgoing, message.delivery e message.send_failed, ligando cada evento ao registro que o originou no seu sistema.

O tutorial Webhooks do WhatsApp: como receber e validar mensagens mostra esse fluxo completo, do endereço no projeto ao processamento em fila, e o guia como evitar mensagens duplicadas aprofunda a idempotência. Se os termos forem novos, o glossário explica o que é um webhook e uma assinatura HMAC.

Quer ver o que mais a API faz? Veja todos os recursos da apiwpp.

Perguntas frequentes

Posso ter um endereço de webhook diferente para cada número?

O endereço é configurado por projeto, e todos os números do projeto enviam para ele. Para separar sistemas ou clientes, crie um projeto para cada um: cada projeto tem o próprio webhook e as próprias chaves de API, na mesma fatura.

O que acontece se o meu servidor ficar fora do ar?

A API tenta cada entrega 6 vezes e pausa as entregas do projeto quando o endpoint falha em sequência. Um evento que não é entregue em 24 horas fica marcado como dead, e você pode reenviar todos de uma vez quando o servidor voltar.

Preciso verificar a assinatura?

É o recomendado. Sem a verificação, qualquer pessoa que descubra o endereço pode enviar eventos falsos para o seu sistema. Com um segredo configurado, cada entrega é assinada com HMAC-SHA256, e a verificação leva poucas linhas em Node.js ou PHP.

Recebo as mensagens que eu mesmo envio?

Só se quiser. O evento message.outgoing é opcional e ativado por projeto; ele avisa de mensagens enviadas pela API e também das digitadas no celular, o que ajuda a manter um histórico completo das conversas no seu sistema.

Todos: Recursos →

O clientRef é o seu identificador de um envio. Repetir a requisição com o mesmo valor devolve o job original com duplicate: true, sem enfileirar outra mensagem, e o clientRef volta nos eventos de entrega e de falha.

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Cada número entra na apiwpp como um aparelho conectado, igual ao WhatsApp Web: escaneie o QR code ou digite um código de 8 caracteres no celular e acompanhe o status pela API e pelo webhook connection.status.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.