Pular para o conteúdo

Webhooks: visão geral

O envelope comum a todos os eventos, os cabeçalhos de cada entrega, as regras de entrega e o catálogo dos 11 eventos que a apiwpp envia.

Ver em Markdown

Tudo o que acontece com um número chega ao seu sistema como um evento: um POST em JSON ao webhookBaseUrl do projeto. Esta página é o mapa: o formato comum, os cabeçalhos, as regras de entrega e a lista de eventos, cada um com a sua página de campos. Para configurar o endpoint, verificar a assinatura e reenviar entregas, siga o guia Webhooks e assinatura.

O envelope

Todo evento chega no mesmo envelope. Só data muda conforme o type:

jsonmessage.incoming
{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-25T12:00:02.000Z",
  "data": {
    "from": "[email protected]",
    "jid": "[email protected]",
    "phone": "+5511988887777",
    "resolvedPhone": "5511988887777",
    "to": "5511900000001:[email protected]",
    "body": "Olá! Tem horário amanhã às 10h?",
    "timestamp": 1790251200,
    "raw": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "IN-TEXT-1" } }
  }
}
CampoTipoDescrição
typestringO tipo do evento, um dos listados em Os eventos
connectionIdstring (uuid)A conexão (o número) que gerou o evento
tenantIdstring (uuid)O projeto que recebe o evento
externalIdstring ou nullO seu identificador da conexão, dado na criação dela; null quando não há
timestampstring (ISO 8601)Quando o evento aconteceu
dataobjetoOs campos do evento, descritos na página de cada type

Todos os campos do envelope vêm sempre (externalId pode ser null). O timestamp do envelope é uma data ISO; dentro de data, os campos timestamp das mensagens são segundos Unix. No evento de teste ping, connectionId, tenantId e externalId vêm null.

Os cabeçalhos

CabeçalhoQuandoConteúdo
Content-TypeSempreapplication/json
X-Webhook-TokenSempreO webhookToken do projeto
X-Sales-TimestampCom webhookSecretSegundos Unix do momento da tentativa; cada nova tentativa é assinada de novo
X-Sales-SignatureCom webhookSecretsha256= + hex(HMAC-SHA256(webhookSecret, timestamp + "." + corpo bruto))
Os seus cabeçalhosCom webhookHeadersOs cabeçalhos extras configurados no projeto

Os cabeçalhos de webhookHeaders podem substituir Content-Type e X-Webhook-Token, mas nunca X-Sales-Timestamp e X-Sales-Signature, que são definidos por último. Verifique a assinatura sobre os bytes do corpo como chegaram e recuse um X-Sales-Timestamp a mais de 300 segundos do seu relógio: o passo a passo, com código em Node.js, PHP e Python, está em Verifique a assinatura. A lista de todos os cabeçalhos da API está em Cabeçalhos.

A entrega

  • Pelo menos uma vez. Novas tentativas e reconexões podem entregar o mesmo evento de novo. Aplique cada evento de forma idempotente, por uma chave do próprio evento: data.messageId nos eventos que a trazem (com data.status nos recibos e data.emoji nas reações); em message.incoming, que não tem messageId, data.jid mais data.raw.key.id; em message.send_failed, data.jobId (ou o seu data.clientRef). Um evento emitido de novo numa reconexão ganha outro timestamp no envelope, então o corpo inteiro só serve de chave para as novas tentativas de uma mesma entrega, que repetem o corpo byte a byte.
  • Sem ordem garantida. Uma entrega em nova tentativa pode chegar depois de eventos mais novos. Ordene pelo timestamp do envelope.
  • Responda 2xx em até 10 segundos. Qualquer outra resposta, um redirecionamento, um erro de rede ou o tempo esgotado conta como falha. São 6 tentativas no total; um evento que não foi entregue em 24 horas fica dead e pode ser reenviado pelo registro de entregas. Os números estão em Limites.
  • Projeto inativo não recebe. Um projeto desativado não recebe webhooks, e desativá-lo fecha as conexões dele sem enviar nenhum evento.
  • O contrato só cresce. Ignore os tipos de evento que você não conhece e os campos que não usa: tipos e campos novos podem aparecer, mas nenhum é renomeado ou removido.

Os eventos

typeQuando chegaCampos principais de data
connection.statusA conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazerstatus, phoneNumber, reason, willReconnect, statusCode, reachoutTimelock
message.incomingAlguém escreveu para o número (texto, mídia, localização), numa conversa individual ou num grupofrom, jid, phone, resolvedPhone, to, body, timestamp, media, location, raw
message.outgoingO número enviou uma mensagem numa conversa individual, pela API ou pelo celular; só com emitOutgoing: true no projetomessageId, origin, clientRef, to, toE164, jid, phone, body, timestamp, mediaType
message.deliveryUma mensagem mudou de status: sent, delivered, read ou failed. Em geral uma que o número enviou, mas pode vir de uma que ele não enviou (com clientRef: null): ignore os messageId que você não conhecemessageId, status, recipient, clientRef, jid, phone, reason
message.send_failedUm envio aceito com clientRef não vai acontecerclientRef, jobId, messageId, to, reason, attempts, jid, phone
message.reactionAlguém reagiu a uma mensagem, ou removeu a reação (emoji vazio)messageId, from, emoji, jid, phone
contact.resolvedUm remetente que chegou só com LID agora tem telefonelid, jid, phone, firstSeenAt, messageCount, source
group.joinedO número entrou num grupo; também uma vez por grupo quando a conexão abre pela primeira vez no processogroupId, groupName, participantCount
group.leftO número foi removido de um grupogroupId, reason
group.updatedUm grupo do número mudou (o nome)groupId, groupName
pingSó no teste do endpoint com POST /tenants/webhook-testmessage

Os dez primeiros estão na seção webhooks da especificação OpenAPI, que pode ser baixada na página inicial da documentação. O ping não faz parte dela.

Os campos de endereço

Os eventos de mensagem identificam a outra pessoa da conversa da mesma forma:

CampoDescrição
jidO JID do WhatsApp da conversa (…@s.whatsapp.net, …@lid ou, em grupos, …@g.us). Vem sempre
phoneO telefone em E.164 (+5511988887777), ou null num grupo ou quando o contato chegou só com um LID que ainda não foi resolvido
clientRefEm message.outgoing, message.delivery e message.send_failed: o clientRef do envio, ou null quando não houve um

Um evento nunca é descartado por não ter telefone. Quando phone é null por causa de um LID, o telefone chega depois em contact.resolved: veja LID e contact.resolved.

Um receptor mínimo

Um endpoint que confere a assinatura, responde logo, descarta repetições e despacha pelo type:

jsNode.js
import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')

function isSigned(rawBody, timestamp, signature) {
  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 produção, guarde as chaves já vistas num banco ou no Redis, com prazo
const seen = new Set()

function dedupeKey(event, rawBody) {
  const { type, data } = event
  if (type === 'message.incoming' && data?.raw?.key?.id) return `${type}:${data.jid}:${data.raw.key.id}`
  if (type === 'message.send_failed') return `${type}:${data.jobId}`
  if (data?.messageId) return `${type}:${data.messageId}:${data.status ?? data.emoji ?? ''}`
  // Sem chave no evento: o corpo, que só se repete nas novas tentativas da mesma entrega
  return createHash('sha256').update(rawBody).digest('hex')
}

const handlers = {
  'connection.status': (e) => console.log('conexão', e.connectionId, e.data.status, e.data.reason ?? ''),
  'message.incoming': (e) => console.log('mensagem de', e.data.phone ?? e.data.jid, e.data.body),
  'message.delivery': (e) => console.log('status', e.data.clientRef, e.data.status),
  'message.send_failed': (e) => console.log('não enviado', e.data.clientRef, e.data.reason),
  'contact.resolved': (e) => console.log('reatribuir', e.data.lid, 'para', e.data.phone),
}

const app = express()

app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401)
  }
  res.sendStatus(204) // responda antes de processar

  const event = JSON.parse(req.body.toString('utf8'))
  const key = dedupeKey(event, req.body)
  if (seen.has(key)) return
  seen.add(key)

  // Tipos desconhecidos são ignorados: o contrato pode ganhar eventos novos
  handlers[event.type]?.(event)
})

app.listen(3000)

Para ver uma entrega de verdade chegando, dispare um ping assinado com o segredo guardado do projeto:

bashVer na referência
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookBaseUrl": "https://crm.example.com/whatsapp/events", "tenantId": "'$TENANT_ID'"}'
200
{ "ok": true, "status": 204, "latencyMs": 184, "error": null }

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026