Métricas e análises

Nota: não existe um endpoint dedicado de analytics de dispatches (/v1/webhooks/dispatches/analytics não está disponível). As métricas de entrega são derivadas da listagem de dispatches usando os filtros de status, responseStatus, onlyErrored e intervalo de datas (daterange*).

Visão Geral

Para acompanhar a saúde de entrega dos seus webhooks (taxa de sucesso/falha, latência, endpoints instáveis), consulte a listagem de dispatches filtrando por período e status, e agregue os resultados do seu lado.

Como obter métricas de um período

Use os filtros de data e status do endpoint de listagem:

GET /v1/webhooks/dispatches?daterangegte=2026-06-01T00:00:00Z&daterangelte=2026-06-30T23:59:59Z

Cabeçalho: SelectKey: sk_live_... (ou sk_test_...). Escopo necessário: webhooks:read.

Receitas úteis

Cada item retornado traz status, attempts, responseStatusCode, responseTime, lastAttemptAt, successAt e createdAt (ver atributos do dispatch) — agregue por dia/endpoint do seu lado para construir gráficos e taxas.

Cálculos sugeridos

• Taxa de sucesso: success ÷ total por dia (campo total do envelope, filtrando por status).
• Latência: média/percentis de responseTime (ms).
• Instabilidade: média de attempts por dispatch — valores altos indicam endpoints que dependem de retentativas.
• Diagnóstico de falhas: concentração de 5xx em responseStatusCode indica indisponibilidade do seu servidor; 4xx costuma indicar problema de configuração (autenticação, rota).

Melhores Práticas

1. Pagine os resultados (limit máximo 100) e agregue do seu lado para períodos longos.
2. Combine filtros (onlyErrored=true + endpoint=...) para investigar falhas de um endpoint específico.
3. Acompanhe responseStatusCode e attempts para distinguir falhas transitórias de persistentes.
4. Para reprocessar uma falha pontual, use o Reenviar Dispatch.

Códigos de Erro