Webhooks
Listar eventos
https://api.kokupay.com/v1/webhooks/events Lista os eventos emitidos para a sua conta, com o mesmo conteúdo enviado por webhook. A consulta não depende da entrega: use-a para conferir o que pode ter se perdido.
curl -X GET 'https://api.kokupay.com/v1/webhooks/events?type=charge.paid&limit=20' \
-H "Authorization: Bearer $KOKU_API_KEY"const response = await fetch('https://api.kokupay.com/v1/webhooks/events?type=charge.paid&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/events?type=charge.paid&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/events?type=charge.paid&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": "evt_2f6b1c9e8a4d4e7f9b3c5a1d0e6f8b27",
"type": "charge.paid",
"version": "v1",
"environment": "production",
"object_type": "charge",
"object_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
"created_at": "2026-10-07T15:32:11.000Z",
"data": {
"charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
"order_reference": "PEDIDO-1001",
"amount_cents": "15990",
"fee_cents": "320",
"net_cents": "15670",
"reserve_cents": "0",
"paid_at": "2026-10-07T15:32:10.000Z",
"end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
"late_payment": false,
"case_id": null
}
}
],
"next_cursor": null
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: webhooks:read. Veja Chaves de API.
Parâmetros de consulta
typestringFiltra pelo tipo de evento (ex.: charge.paid).
até 60 caracteres
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[].idstringIdentificador do evento (evt_...). É o mesmo em todas as tentativas de entrega: use-o para não processar duas vezes.
items[].typestringTipo do evento (ex.: charge.paid).
items[].versionstringVersão do formato do evento (v1).
items[].environmentstringAmbiente: production (sandbox está reservado para o ambiente de testes, em preparação).
Valores: sandbox, production
items[].object_typestring ou nullTipo do objeto do evento (ex.: charge).
items[].object_idstring ou nullIdentificador do objeto.
items[].created_atstring (data e hora)Momento do fato.
items[].dataobjetoDados do evento. O formato de cada tipo está em Eventos e payloads.
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.