# Entregas de webhook

Fonte: https://apiwpp.com/docs/api/registros/listar-entregas-de-webhook
Seção: Registros
Atualizado em: 2026-09-28

`GET /webhooks/deliveries`

Lista as entregas de webhook do projeto, das mais novas para as mais antigas: uma linha por evento enviado ao seu endpoint, atualizada a cada tentativa. `counts` ignora o filtro `state`; `stats` resume todas as linhas guardadas do filtro de projeto: `successRate` é a porcentagem de entregues (de 0 a 100, com uma casa decimal) e `avgLatencyMs` é o tempo médio de resposta das entregues. Escopo necessário: `logs:read`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `state` | `string` | não | Só as entregas neste estado: `delivered` (entregue), `retry` (aguardando nova tentativa) ou `dead` (tentativas esgotadas). Não muda `counts` nem `stats`. Valores: `"delivered"`, `"retry"`, `"dead"`. |
| `tenantId` | `string` | não | Filtra por projeto (`tenantId`). Com uma chave de API, a lista já cobre só o projeto da chave, então este filtro só aceita esse mesmo projeto; outro responde `404`. |
| `limit` | `integer` | não | Quantas linhas trazer, das mais novas para as mais antigas. Padrão 60; um valor acima de 200 é tratado como 200. Não há paginação: para ver linhas mais antigas, estreite os filtros. (mínimo 1; padrão: 60) |

## Exemplo de requisição

### cURL

```bash
curl "https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/webhooks/deliveries", [
        'state' => 'dead',
        'limit' => '20',
    ]);
```

### Python

```python
import requests

response = requests.get(
    "https://api.apiwpp.com/webhooks/deliveries",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "state": "dead",
        "limit": "20",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | `deliveries`, as linhas das mais novas para as mais antigas (cada uma com `id`, `tenantId`, `connectionId`, `eventType`, `url`, `state`, `httpStatus`, `error`, `latencyMs`, `attempts`, `maxAttempts`, `nextAttemptAt`, `signed`, `payload`, `createdAt` e `updatedAt`); `counts`, com o total (`all`) e o número por estado; e `stats`. Sem nenhuma entrega registrada, `successRate` vem `null`; sem nenhuma entregue, `avgLatencyMs` vem `null`. |
| 400 | `FST_ERR_VALIDATION` | Um filtro não segue o schema da operação: `state` fora da lista, ou `limit` que não é um inteiro maior que zero; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A chave não tem o escopo `logs:read`; a mensagem cita o escopo (`This credential lacks the logs:read scope`). |
| 404 |  | O filtro `tenantId` aponta para um projeto que não é da chave (`{"error": "Tenant not found"}`): o projeto de outra pessoa responde exatamente como um que não existe. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "deliveries": [
    {
      "id": "9c2d5e6f-7a8b-4c9d-8e0f-3a4b5c6d7e8f",
      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
      "eventType": "message.delivery",
      "url": "https://crm.example.com/api/whatsapp/events",
      "state": "delivered",
      "httpStatus": 200,
      "error": null,
      "latencyMs": 120,
      "attempts": 1,
      "maxAttempts": 6,
      "nextAttemptAt": null,
      "signed": true,
      "payload": {
        "type": "message.delivery",
        "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
        "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
        "externalId": "shop-42",
        "timestamp": "2026-09-24T12:00:02.000Z",
        "data": {
          "messageId": "3EB0C767D26A1D8A3F52",
          "status": "delivered",
          "recipient": "5511988887777",
          "jid": "5511988887777@s.whatsapp.net",
          "phone": "+5511988887777",
          "clientRef": "crm-msg-1"
        }
      },
      "createdAt": "2026-09-24T12:00:02.000Z",
      "updatedAt": "2026-09-24T12:00:02.000Z"
    }
  ],
  "counts": {
    "all": 1,
    "delivered": 1,
    "retry": 0,
    "dead": 0
  },
  "stats": {
    "successRate": 100,
    "avgLatencyMs": 120
  }
}
```

## Detalhes

**Os estados.** `delivered`: o endpoint respondeu 2xx. `retry`: a última tentativa falhou e há outra agendada para `nextAttemptAt`. `dead`: as tentativas acabaram (6 no total, a primeira mais 5 novas tentativas) ou a entrega passou de 24 horas sem sucesso; ela só sai daí por um reenvio.

**Os campos de cada linha.** `eventType` é o `type` do evento (`message.incoming`, `connection.status`…). `url` é o endpoint usado e `signed` diz se a entrega levou a assinatura `X-Sales-Signature`. `attempts` conta as tentativas feitas e `maxAttempts` é o total permitido (6). `httpStatus` e `latencyMs` são da última tentativa (`null` quando não houve resposta). `error` explica a última falha: `HTTP 500` (o seu endpoint respondeu um status fora de 2xx), `timeout` (sem resposta em 10 s), `redirect not followed: HTTP 301 to …` (redirecionamentos não são seguidos), `circuit open` (entregas ao projeto pausadas depois de falhas seguidas), `max age exceeded (…)` (passou de 24 horas sem sucesso) ou a mensagem de erro da conexão (DNS, TLS, recusa). `payload` é o corpo exato que foi enviado, envelope incluído.

**Payload grande.** Um corpo com mais de 256 KB (um `message.incoming` com a mensagem bruta, por exemplo) não é guardado: `payload` vem como `{"_truncated": true, "type": "…", "bytes": 312000}`. Essa entrega só pode ser reenviada enquanto ainda está na fila interna de novas tentativas ou de entregas mortas da apiwpp; depois disso, o reenvio responde `409`.

**Retenção.** Os registros ficam guardados por 7 dias por padrão; depois disso, saem da lista e das contagens.

Guia: [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
