Webhooks
Listar endpoints de webhook
GET
https://api.kokupay.com/v1/webhooks/endpoints Lista os endpoints cadastrados, com a situação de cada um e as falhas seguidas mais recentes.
GET/v1/webhooks/endpoints
curl -X GET 'https://api.kokupay.com/v1/webhooks/endpoints' \
-H "Authorization: Bearer $KOKU_API_KEY"const response = await fetch('https://api.kokupay.com/v1/webhooks/endpoints', {
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/endpoints",
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/endpoints');
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);200Resposta
{
"items": [
{
"id": "71c3e9a5-4f2d-4b8e-a06c-9d5e2f1b7a38",
"url": "https://loja.example.com/webhooks/koku",
"event_types": [
"charge.paid",
"charge.expired",
"charge.failed",
"charge.refunded"
],
"status": "active",
"secret_last4": "4Ko7",
"created_at": "2026-10-07T14:10:00.000Z",
"consecutive_failures": 0,
"paused_until": null
}
]
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: webhooks:read. Veja Chaves de API.
Resposta 200
itemslista de objetosItens da página.
items[].idstring (uuid)Identificador do endpoint.
items[].urlstringURL cadastrada.
items[].event_typeslista de stringTipos de evento assinados (vazio = todos).
items[].statusstringSituação: active ou disabled.
items[].secret_last4string ou nullÚltimos 4 caracteres do segredo, para conferência.
items[].created_atstring (data e hora)Cadastro do endpoint.
items[].consecutive_failuresinteiroFalhas técnicas seguidas nas últimas entregas (0 = saudável).
items[].paused_untilstring (data e hora) ou nullEntregas pausadas até este horário depois de falhas seguidas (null = sem pausa).
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"). |
| 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.