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

## Listar

### GET /public/v1/deliveries

| Parâmetro | O que é |
| --- | --- |
| status | pending, delivering, delivered ou failed. Sem ele, vêm todas. |
| limit | Até 200 por página. Padrão 50. |
| 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
  }
}
```

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

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

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

## 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