Docs
Acessar painel

Webhooks

Listar endpoints de webhook

GEThttps://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"
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 objetos

Itens da página.

items[].idstring (uuid)

Identificador do endpoint.

items[].urlstring

URL cadastrada.

items[].event_typeslista de string

Tipos de evento assinados (vazio = todos).

items[].statusstring

Situaçã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_failuresinteiro

Falhas técnicas seguidas nas últimas entregas (0 = saudável).

items[].paused_untilstring (data e hora) ou null

Entregas pausadas até este horário depois de falhas seguidas (null = sem pausa).

Erros

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
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.