Pular para o conteúdo

Entregas de webhook

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.

Ver em Markdown

Parâmetros de consulta

statestring

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"
tenantIdstring

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.

limitinteger

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 1padrão: 60

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200deliveries, 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.
400FST_ERR_VALIDATIONUm 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.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
403A chave não tem o escopo logs:read; a mensagem cita o escopo (This credential lacks the logs:read scope).
404O 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.
429Requisiçõ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.Cabeçalho: Retry-After

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

Esta página ajudou? · Atualizado em 28 set 2026