Docs
Acessar painel

Webhooks

Listar entregas

GEThttps://api.kokupay.com/v1/webhooks/deliveries

Mostra o resultado técnico de cada tentativa de entrega aos seus endpoints. Uma falha de entrega nunca altera cobrança, saldo ou extrato.

GET/v1/webhooks/deliveries
curl -X GET 'https://api.kokupay.com/v1/webhooks/deliveries?status=delivered&limit=20' \
  -H "Authorization: Bearer $KOKU_API_KEY"
200Resposta
{
  "items": [
    {
      "id": "c58a2e1f-7d39-4b6c-9e04-2a1f8d7c3b65",
      "endpoint_id": "71c3e9a5-4f2d-4b8e-a06c-9d5e2f1b7a38",
      "endpoint_url": "https://loja.example.com/webhooks/koku",
      "event_id": "evt_2f6b1c9e8a4d4e7f9b3c5a1d0e6f8b27",
      "event_type": "charge.paid",
      "status": "delivered",
      "attempts": 1,
      "last_response_status": 200,
      "last_response_ms": 84,
      "last_error": null,
      "last_attempt_at": "2026-10-07T15:32:12.000Z",
      "next_attempt_at": null,
      "delivered_at": "2026-10-07T15:32:12.000Z",
      "created_at": "2026-10-07T15:32:11.000Z"
    }
  ],
  "next_cursor": null
}

Autenticação

Authorization: Bearer <sua chave de API>

Escopo exigido: webhooks:read. Veja Chaves de API.

Parâmetros de consulta

statusstring

Filtra pelo resultado técnico da entrega.

Valores: pending, delivered, failed, dead_letter

endpoint_idstring (uuid)

Filtra por endpoint.

cursorstring

Cursor devolvido em next_cursor da página anterior.

até 2000 caracteres

limitinteiro

Itens por página.

de 1 a 200

Resposta 200

itemslista de objetos

Itens da página.

items[].idstring (uuid)

Identificador da entrega.

items[].endpoint_idstring (uuid)

Endpoint de destino.

items[].endpoint_urlstring

URL do endpoint.

items[].event_idstring

Evento entregue.

items[].event_typestring

Tipo do evento.

items[].statusstring

Resultado técnico: pending, delivered, failed ou dead_letter (tentativas esgotadas).

items[].attemptsinteiro

Tentativas feitas.

items[].last_response_statusinteiro ou null

Status HTTP da última resposta do seu endpoint.

items[].last_response_msinteiro ou null

Tempo da última resposta, em milissegundos.

items[].last_errorstring ou null

Último erro técnico (ex.: tempo esgotado).

items[].last_attempt_atstring (data e hora) ou null

Última tentativa.

items[].next_attempt_atstring (data e hora) ou null

Próxima tentativa agendada.

items[].delivered_atstring (data e hora) ou null

Entrega confirmada (resposta 2xx).

items[].created_atstring (data e hora)

Criação da entrega.

next_cursorstring ou null

Cursor da próxima página; null quando não há mais itens.

Erros

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
422validation_errorParâmetro inválido (details.fields indica qual).
429rate_limitedLimite de requisições excedido. Aguarde o tempo de Retry-After.
500internal_errorFalha inesperada. Repita com a mesma Idempotency-Key; persistindo, envie o correlation_id à Koku (veja Suporte).

Formato do corpo de erro em Erros.