message.delivery
Uma mensagem enviada pelo número mudou de status.
Uma mensagem mudou de status: sent, delivered, read ou failed. Em geral é uma que o número enviou, pela API ou digitada no celular. Chega a todos os projetos, sem configuração.
Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente.
Um evento por mudança. Uma mensagem normalmente passa por sent, delivered e read, com um evento para cada status. Cada entrega tem as próprias novas tentativas, então um status pode chegar repetido ou depois do seguinte: guarde o status mais avançado de cada messageId e não volte de read para delivered.
Correlacionar com o seu envio. Quando a mensagem saiu por POST /connections/{id}/send com um clientRef, ele volta em cada status. O vínculo entre o messageId e o clientRef vale por 72 horas: um status mais tardio chega com clientRef: null, e então você correlaciona pelo messageId, que já veio nos status anteriores da mesma mensagem (e em message.outgoing, se o projeto o ativou). Se a consulta a esse vínculo falhar, o evento sai assim mesmo, com clientRef: null. Veja Idempotência.
failed com reason: reachout_timelocked. O WhatsApp recusou a mensagem como contato frio (erro de confirmação 463, em geral para um contato com quem o número nunca conversou). Ela não foi entregue e não é tentada de novo, e reenviar piora a restrição. Quando a conta entra num bloqueio, a conexão avisa em connection.status com reason: reachout_timelock; veja Bloqueio temporário de novas conversas. Um failed sem reason é uma falha que o WhatsApp não explicou.
Status de mensagens que o número não enviou. O WhatsApp também manda atualizações de status de mensagens que não saíram deste número, e elas viram message.delivery do mesmo jeito, com clientRef: null. Compare o messageId com os seus envios (o de message.outgoing e dos status anteriores) e ignore os ids que você não conhece.
failed não é message.send_failed. Aqui a mensagem saiu e o WhatsApp a recusou. message.send_failed é o caso em que a apiwpp desistiu de um envio aceito antes de ele sair: não há messageId, e o evento só existe para envios com clientRef.
Registro de mensagens. O status dos envios pela API também é gravado no registro de mensagens.
Entrega. Um POST com Content-Type: application/json ao webhookBaseUrl do projeto, feito pelo menos uma vez; um projeto inativo não recebe webhooks. Responda 2xx em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (3xx) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, 6 tentativas no total, e então fica dead. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica dead. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo timestamp do envelope. Reenvie as entregas dead com POST /webhooks/deliveries/{id}/resend ou POST /webhooks/deliveries/resend-dead.
Assinatura. X-Webhook-Token vem sempre, com o webhookToken do projeto, junto com os webhookHeaders personalizados. Com um webhookSecret, cada tentativa também traz X-Sales-Timestamp (segundos unix da tentativa) e X-Sales-Signature: calcule "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo)) sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio. Veja Webhooks e assinatura.
Guia: Idempotência
Cabeçalhos da entrega
X-Webhook-TokenstringsempreO webhookToken do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com PATCH /tenants/{id}. Os webhookHeaders personalizados do projeto também são enviados.
X-Sales-TimestampstringSó quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio.
X-Sales-SignaturestringSó quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante.
Envelope
typestringsempre presenteO tipo do evento, que decide o formato de data. Ignore os tipos que você não conhece: a lista de eventos pode crescer.
connectionIdstring · uuidsempre presenteO id (UUID) da conexão, ou seja, do número, que gerou o evento.
tenantIdstring · uuidsempre presenteO id (UUID) do projeto dono da conexão.
externalIdstring | nullsempre presenteO externalId que você informou ao criar a conexão, para ligá-la a um registro seu. null quando a conexão foi criada sem ele.
timestampstring · date-timesempre presenteQuando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho X-Sales-Timestamp.
Campos de data
messageIdstringsempre presenteO id da mensagem no WhatsApp: o mesmo de message.outgoing e dos status anteriores desta mensagem. Guarde o status mais avançado por esta chave.
statusstringsempre presentesent: o servidor do WhatsApp recebeu a mensagem. delivered: ela chegou ao aparelho do destinatário. read: foi lida (ou, numa mensagem de voz, ouvida). failed: não foi entregue.
"sent", "delivered", "read", "failed"recipientstringsempre presenteCampo legado: o JID sem @s.whatsapp.net (um LID passa inteiro). Prefira jid e phone.
jidstringsempre presenteJID bruto da outra pessoa (…@s.whatsapp.net ou …@lid). Sempre presente.
phonestring | nullsempre presenteTelefone da outra pessoa em E.164 (por exemplo, +5511999999999). null quando a conversa usa um LID que a apiwpp não conseguiu resolver, ou numa conversa em grupo; o evento nunca é descartado por isso.
clientRefstring | nullsempre presenteO clientRef passado a POST /connections/{id}/send para esta mensagem. null quando o envio não tinha um, quando a mensagem não saiu pela API ou depois de 72 horas do envio.
reasonstringSó com status: failed, quando o WhatsApp disse o motivo; ausente nos outros casos. reachout_timelocked: o WhatsApp recusou a mensagem como contato frio (erro 463); ela não foi entregue nem é tentada de novo.
"reachout_timelocked"