Entregas do webhook

Cada evento enfileirado tem uma entrega. As tentativas atualizam a mesma linha, mantendo seu identificador. Consulte se o endpoint aceitou, confira a última resposta e reenvie falhas.

Listar# (link para esta seção)

curl "https://api.patrociniotech.com/public/v1/deliveries?status=failed&limit=100" \
  -H "Authorization: Bearer SUA_CHAVE"

{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": 1841,
        "event": "message.status",
        "status": "failed",
        "attempts": 7,
        "last_status": 502,

Para investigar uma mensagem, filtre pelo ID e pelo tipo do evento. Continue usando os mesmos filtros ao passar o cursor next_before_id.

curl --get "https://api.patrociniotech.com/public/v1/deliveries" \
  -H "Authorization: Bearer SUA_CHAVE" \
  --data-urlencode "message_id=wamid.EXEMPLO" \
  --data-urlencode "event=message.status" \
  --data-urlencode "limit=50"

Ver uma entrega# (link para esta seção)

Igual à listagem, mais last_error: um resumo da falha ou um trecho da última resposta, guardado mesmo em sucesso. Credenciais conhecidas são ocultadas. Não devolva dados sensíveis no corpo do seu endpoint.

O trecho da resposta é limitado e pode estar incompleto; não o interprete como um JSON completo. Respostas gzip e deflate são decodificadas antes do registro. Se não for possível ler o conteúdo comprimido, o diagnóstico informa essa limitação e preserva o resultado HTTP.

curl "https://api.patrociniotech.com/public/v1/deliveries/1841" \
  -H "Authorization: Bearer SUA_CHAVE"

Reenviar# (link para esta seção)

Devolve a entrega para a fila. Vale para failed (esgotou as tentativas) e para delivered (reprocessar do seu lado). O corpo é assinado de novo no disparo, com o timestamp do momento, então uma entrega reenviada horas depois não esbarra na janela de replay do seu endpoint.

Essa ação reenvia somente o evento ao seu endpoint. Não envia outra mensagem ao contato no WhatsApp.

curl -X POST "https://api.patrociniotech.com/public/v1/deliveries/1841/retry" \
  -H "Authorization: Bearer SUA_CHAVE"

Recoloca até 500 entregas com falha na fila por chamada. Devolve requeued com quantas voltaram. Corrija o endpoint antes de usar; se houver mais registros, confira a fila novamente antes de solicitar outro lote.

curl -X POST "https://api.patrociniotech.com/public/v1/deliveries/retry-failed" \
  -H "Authorization: Bearer SUA_CHAVE"

Rotina sugerida# (link para esta seção)

Consulte falhas periodicamente e avise a equipe responsável. O exemplo abaixo verifica uma página da fila; não solicita reenvio automaticamente.

async function varrerFalhas() {
  const r = await fetch(`https://api.patrociniotech.com/public/v1/deliveries?status=failed&limit=200`, {
    headers: { Authorization: `Bearer ${process.env.PT_API_KEY}` },
  });
  const { data } = await r.json();
  if (!r.ok || !data?.deliveries) throw new Error("Falha ao consultar as entregas.");
  if (!data.deliveries.length) return;

  // alertar é uma função do seu sistema. Confirme a recuperação antes do reenvio.
  await alertar(`${data.deliveries.length} entregas de webhook falharam`);

  // Após confirmar a recuperação do endpoint, solicite o reenvio em uma ação separada.
}

Por quanto tempo ficam disponíveis# (link para esta seção)

Por padrão, entregas com status=delivered são mantidas por 30 dias e as que terminaram em failed por 60 dias, contados de created_at. A resposta da listagem informa os prazos efetivos em data.retention; eles podem variar conforme a configuração do serviço.

A manutenção remove registros em lotes, por isso alguns podem continuar visíveis depois do prazo. Eventos em pending ou delivering não são removidos somente por idade. Um reenvio manual preserva a data de criação e não reinicia a retenção.

Situações# (link para esta seção)

next_attempt_at só representa um agendamento ativo quando o estado é pending. Nos demais estados pode conservar o horário da tentativa anterior. delivered_at registra uma aceitação anterior e não substitui o estado atual depois de um reenvio manual.