# Entregas do webhook

Consulte as tentativas de entrega ao seu endpoint e recupere eventos que falharam.

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.

> Esta fila mostra a entrega do **webhook ao seu servidor**. Ela não é uma consulta do status atual de uma mensagem no WhatsApp. Um evento pode informar uma mensagem entregue mesmo quando o seu endpoint falhou ao receber essa informação.

## Listar

### GET /public/v1/deliveries

| Parâmetro | O que é |
| --- | --- |
| status | pending, delivering, delivered ou failed. Sem ele, vêm todas. |
| message\_id | ID da mensagem para conferir apenas seus eventos. Até 128 caracteres. Pode ser combinado com event e status. |
| event | message.status, message.received, contact.marketing\_opt\_out, template.status ou template.quality. Sem ele, vêm todos os tipos enfileirados. |
| limit | De 1 a 200 por página. Padrão 50. Valores fora do intervalo retornam 422. |
| before\_id | Cursor: traz o que é anterior a esse id. Use o next\_before\_id da resposta. |

curl

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

resposta

```text
{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": 1841,
        "event": "message.status",
        "status": "failed",
        "attempts": 7,
        "last_status": 502,
        "next_attempt_at": "2026-07-31T01:12:30Z",
        "delivered_at": null,
        "created_at": "2026-07-29T18:00:00Z",
        "message_id": "wamid.HBgNNTUyMT...",
        "message_status": "delivered",
        "recipient": "5521999999999",
        "client_ref": "pedido-8421"
      }
    ],
    "next_before_id": null,
    "retention": {
      "delivered_days": 30,
      "failed_days": 60,
      "pending_pruned": false,
      "delivering_pruned": false,
      "measured_from": "created_at"
    }
  }
}
```

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 · eventos de uma mensagem

```bash
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"
```

| Campo do registro | Como interpretar |
| --- | --- |
| status | Situação da entrega HTTP deste evento ao seu endpoint. |
| message\_status | Status do WhatsApp informado neste evento, quando disponível. Outro evento mais recente pode ter atualizado a mensagem. |
| last\_status | Código HTTP retornado pelo seu endpoint na última tentativa, quando houve resposta. |

> Para consultar a próxima página, envie o `next_before_id` recebido como` before_id`. Mantenha os filtros e continue até o cursor ser nulo.

## Ver uma entrega

### GET /public/v1/deliveries/{id}

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.

> Atenção: Uma resposta `2xx` confirma o recebimento HTTP. Se o evento não produziu o resultado esperado, confira também os registros de processamento no seu sistema.

curl

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

## Reenviar

### POST /public/v1/deliveries/{id}/retry

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.

> O reenvio mantém `delivery_id` e o histórico de tentativas. Se o evento já foi aplicado, a deduplicação deve continuar impedindo efeitos repetidos. Para refazer uma operação de negócio, use seu próprio processo de recuperação; reenviar o webhook não cria outro evento.

curl

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

### POST /public/v1/deliveries/retry-failed

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

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

## Rotina sugerida

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

Node.js

```javascript
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

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.

> Guarde os eventos processados no seu sistema. A fila serve para diagnóstico e recuperação dentro desses prazos; uma lista vazia ou um 404 não comprova que a mensagem no WhatsApp deixou de ser entregue.

## Situações

| status | O que significa |
| --- | --- |
| pending | Na fila, esperando a próxima tentativa. |
| delivering | Uma tentativa de entrega está em andamento. |
| delivered | Seu endpoint respondeu 2xx. Isso não confirma o processamento da operação no seu sistema. |
| failed | Tentativas esgotadas ou webhook desativado/removido. Consulte last\_error antes de reenviar. |

`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.

---

Fonte: https://patrociniotech.com/documentacao-api/entregas
Índice para IA: https://patrociniotech.com/documentacao-api/llms.txt