message.send_failed
Um envio na fila com clientRef não vai acontecer.
Um envio aceito por POST /connections/{id}/send com clientRef não vai acontecer: a apiwpp desistiu dele. É o único aviso de que um envio que respondeu 202 não vai sair, porque repetir a requisição com o mesmo clientRef continua respondendo 200 com "duplicate": true durante os 7 dias da reserva. Um envio sem clientRef nunca gera este evento, porque não haveria como correlacioná-lo.
A apiwpp tenta cada envio da fila até 3 vezes, com espera crescente entre as tentativas. reason diz por que ela desistiu:
attempts_exhausted: as 3 tentativas falharam, por exemplo porque a conexão caiu ou o arquivo de media.url não pôde ser baixado.
lease_expired: o envio travou na última tentativa (num reinício do serviço, por exemplo) sem ser confirmado. A mensagem pode ter saído mesmo assim.
not_on_whatsapp: o número de to não está no WhatsApp. Não há novas tentativas. Para conferir antes de enviar, use POST /connections/{id}/contacts/check.
reachout_timelocked: a conta está num bloqueio temporário de novas conversas do WhatsApp, e o envio foi recusado sem ser tentado, porque cada tentativa aprofundaria a restrição. O connection.status com reason: reachout_timelock avisa o início do bloqueio, e com reason: reachout_timelock_lifted, o fim. Veja Limites de envio.
A prova de envio vale. messageId é sempre null: a falha aconteceu antes (ou no lugar) de um envio que a apiwpp possa confirmar. Se, depois deste evento, chegar um message.outgoing ou um message.delivery com o mesmo clientRef, a mensagem saiu: fique com a prova de envio.
Para mandar de novo, faça outro POST /connections/{id}/send com um clientRef novo, como pedido-1234-2: o mesmo valor só responderia duplicate. Veja Idempotência.
Cancelar um envio com DELETE /connections/{id}/queue/{jobId} não gera este evento. Se um envio aceito nunca se confirmar (nem este evento, nem uma prova de envio), concilie pelo registro de mensagens, que procura também pelo clientRef: GET /messages?q=<clientRef>.
Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente, pela chave data.jobId.
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
clientRefstringsempre presenteO clientRef que você mandou no envio: é por ele que você encontra o registro do seu lado.
jobIdstringsempre presenteO jobId que a resposta 202 do envio trouxe.
messageIdstring | nullsempre presenteSempre null: nenhum envio foi confirmado, então não há id do WhatsApp.
tostringsempre presenteO to do envio, como foi enfileirado.
jidstringsempre presenteJID do destinatário, montado a partir de to (o próprio to, quando ele já é um JID). Sempre presente.
phonestring | nullsempre presenteTelefone do destinatário em E.164 (por exemplo, +5511988887777). null quando to é um LID (…@lid) ou não traz um telefone, como o JID de um grupo. Veja LID e contact.resolved.
reasonstringsempre presentePor que a apiwpp desistiu: attempts_exhausted (as tentativas se esgotaram), lease_expired (o envio travou na última tentativa), not_on_whatsapp (o número não está no WhatsApp) ou reachout_timelocked (bloqueio temporário de novas conversas).
"attempts_exhausted", "lease_expired", "not_on_whatsapp", "reachout_timelocked"attemptsnumbersempre presenteQuantas vezes o envio saiu da fila para ser processado, no máximo 3.