Docs
Acessar painel

Webhooks

Cadastrar endpoint de webhook

POSThttps://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"
  ]
}'
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ório

URL 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 string

Tipos de evento a receber. Vazio ou omitido = todos.

até 30 itens

Resposta 201

idstring (uuid)

Identificador do endpoint.

signing_secretstring

Segredo de assinatura. Exibido uma única vez: guarde-o em local seguro.

Erros

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
409conflictLimite de endpoints ativos atingido (details.reason = "webhook_endpoint_limit").
422validation_errorURL inválida, sem HTTPS, apontando para rede privada (details.reason = "ssrf_blocked") ou tipo de evento desconhecido.
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.