Webhook deliveries

Cada webhook que o hub dispara gera um row em webhook_deliveries. Permite debug (ver payload + signature) e replay (reenviar pro consumer). Admin key.

`GET /v1/webhook-deliveries`

Lista paginada com filtros.

Query params

Param	Tipo	Notas
`app_id`	ULID opcional	filtrar por app
`status`	`pending` \| `delivered` \| `failed` opcional
`event`	string opcional	nome do evento (`message.received`, etc)
`before`	ISO datetime opcional	cursor — `created_at` do ultimo item
`limit`	int 1-200, default 50

Response

{
  "data": [
    {
      "id": "01HZTQ...",
      "app_id": "...",
      "event": "message.received",
      "status": "delivered",
      "attempts": 1,
      "max_attempts": 7,
      "last_status_code": 200,
      "last_error": null,
      "last_latency_ms": 84,
      "next_attempt_at": null,
      "delivered_at": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "next_before": "2026-04-30T12:00:00.000Z"
}

Note: payload nao vem nessa rota — use o endpoint abaixo.

`GET /v1/webhook-deliveries/:id`

Mesmo schema do item, sem payload.

`GET /v1/webhook-deliveries/:id/payload`

Retorna payload + signature completos pra debug.

{
  "id": "01HZTQ...",
  "event": "message.received",
  "payload": {
    "event": "message.received",
    "timestamp": "...",
    "data": { ... }
  },
  "signature": "sha256=450c876b6e8a...",
  "created_at": "..."
}

Use pra:

Confirmar que o payload que o consumer recebeu bate com o que o hub mandou
Recalcular a signature do seu lado e validar (debug de problema HMAC)
Reenviar manualmente pra um endpoint diferente (replay com URL custom — ainda nao tem, use replay)

`POST /v1/webhook-deliveries/:id/replay`

Reset + reenfileira (mesmo se ja delivered ou failed). Audita em audit_events.

curl -X POST "$HUB/v1/webhook-deliveries/01HZTQ.../replay" \
  -H "Authorization: Bearer $ADMIN_KEY"

Atencao: replay envia pra webhook_url atual da app, com signature recalculada com webhook_secret atual. Isso e proposital — permite testar apos rotar secret ou trocar URL. Se voce quer reproduzir o cenario original exato, use o endpoint /payload e simule manualmente.

Retorna o registro apos enfileirar:

{
  "id": "...",
  "status": "pending",
  "attempts": 0,
  "next_attempt_at": "..."
}

Politica de retry

7 tentativas total com backoff exponencial:

[30s, 2min, 10min, 1h, 6h, 24h]

Tentativa 1 imediata. Falha → espera 30s pra tentativa 2. Falha de novo → 2min pra 3a. Etc.

Apos 7a tentativa, status vira failed. Nao retenta automaticamente apos failed — use POST /:id/replay se quiser.

Quando hub considera “falha”

HTTP timeout (WEBHOOK_TIMEOUT_MS, default 10s)
Status 5xx
Status 408/429 (retentar)

Quando hub para de retentar (vai pra `failed` na hora)

Status 4xx exceto 408/429 (payload errado, nao adianta retentar)
Erro de DNS/rede que nao e timeout

Retencao

webhook_deliveries em status terminal (delivered ou failed) sao podadas apos WEBHOOK_DELIVERIES_RETENTION_DAYS (default 30 dias).

Webhook deliveries

GET /v1/webhook-deliveries