Webhooks
Listar entregas
https://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.
curl -X GET 'https://api.kokupay.com/v1/webhooks/deliveries?status=delivered&limit=20' \
-H "Authorization: Bearer $KOKU_API_KEY"const response = await fetch('https://api.kokupay.com/v1/webhooks/deliveries?status=delivered&limit=20', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
},
});
const data = await response.json();
console.log(response.status, data);import os
import requests
response = requests.request(
"GET",
"https://api.kokupay.com/v1/webhooks/deliveries?status=delivered&limit=20",
headers={
"Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init('https://api.kokupay.com/v1/webhooks/deliveries?status=delivered&limit=20');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);{
"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
statusstringFiltra pelo resultado técnico da entrega.
Valores: pending, delivered, failed, dead_letter
endpoint_idstring (uuid)Filtra por endpoint.
cursorstringCursor devolvido em next_cursor da página anterior.
até 2000 caracteres
limitinteiroItens por página.
de 1 a 200
Resposta 200
itemslista de objetosItens da página.
items[].idstring (uuid)Identificador da entrega.
items[].endpoint_idstring (uuid)Endpoint de destino.
items[].endpoint_urlstringURL do endpoint.
items[].event_idstringEvento entregue.
items[].event_typestringTipo do evento.
items[].statusstringResultado técnico: pending, delivered, failed ou dead_letter (tentativas esgotadas).
items[].attemptsinteiroTentativas feitas.
items[].last_response_statusinteiro ou nullStatus HTTP da última resposta do seu endpoint.
items[].last_response_msinteiro ou nullTempo 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 nullPróxima tentativa agendada.
items[].delivered_atstring (data e hora) ou nullEntrega confirmada (resposta 2xx).
items[].created_atstring (data e hora)Criação da entrega.
next_cursorstring ou nullCursor da próxima página; null quando não há mais itens.
Erros
| Status | Código | Quando |
|---|---|---|
| 401 | unauthorized | Chave ausente, inválida, revogada ou expirada. |
| 403 | forbidden | A chave não tem o escopo exigido (details.reason = "missing_scope"). |
| 422 | validation_error | Parâmetro inválido (details.fields indica qual). |
| 429 | rate_limited | Limite de requisições excedido. Aguarde o tempo de Retry-After. |
| 500 | internal_error | Falha inesperada. Repita com a mesma Idempotency-Key; persistindo, envie o correlation_id à Koku (veja Suporte). |
Formato do corpo de erro em Erros.