Webhooks
Cadastrar endpoint de webhook
POST
https://api.kokupay.com/v1/webhooks/endpoints Cadastra a URL que vai receber os eventos. O segredo de assinatura (signing_secret) é devolvido uma única vez: guarde-o em local seguro.
POST/v1/webhooks/endpoints
curl -X POST 'https://api.kokupay.com/v1/webhooks/endpoints' \
-H "Authorization: Bearer $KOKU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://loja.example.com/webhooks/koku",
"event_types": [
"charge.paid",
"charge.expired",
"charge.failed",
"charge.refunded"
]
}'const response = await fetch('https://api.kokupay.com/v1/webhooks/endpoints', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://loja.example.com/webhooks/koku',
event_types: ['charge.paid', 'charge.expired', 'charge.failed', 'charge.refunded'],
}),
});
const data = await response.json();
console.log(response.status, data);import os
import requests
response = requests.request(
"POST",
"https://api.kokupay.com/v1/webhooks/endpoints",
headers={
"Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
},
json={
"url": "https://loja.example.com/webhooks/koku",
"event_types": ["charge.paid", "charge.expired", "charge.failed", "charge.refunded"],
},
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 => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://loja.example.com/webhooks/koku',
'event_types' => [
'charge.paid',
'charge.expired',
'charge.failed',
'charge.refunded',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);201Resposta
{
"id": "71c3e9a5-4f2d-4b8e-a06c-9d5e2f1b7a38",
"signing_secret": "whsec_Zq4m8Tn2Vb7Lk1Xc9Rd5Hs3Wf6Jp0Ga2Ye8Ui4Ko7"
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: webhooks:write. Veja Chaves de API.
Corpo da requisição
JSON (Content-Type: application/json). Campos não listados são recusados com 422.
urlstringobrigatórioURL HTTPS pública que vai receber os eventos (até 2000 caracteres). Redes privadas e endereços locais são recusados.
10 a 2000 caracteres
event_typeslista de stringTipos de evento a receber. Vazio ou omitido = todos.
até 30 itens
Resposta 201
idstring (uuid)Identificador do endpoint.
signing_secretstringSegredo de assinatura. Exibido uma única vez: guarde-o em local seguro.
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"). |
| 409 | conflict | Limite de endpoints ativos atingido (details.reason = "webhook_endpoint_limit"). |
| 422 | validation_error | URL inválida, sem HTTPS, apontando para rede privada (details.reason = "ssrf_blocked") ou tipo de evento desconhecido. |
| 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.