Eventos de webhook

Um evento é o registro de algo que aconteceu na organização — um token criado, um token revogado. Ao cadastrar um endpoint, você marca os eventos que ele quer receber; cada vez que um deles acontece, o Dashboard Mágico envia uma entrega para o endpoint.

Eventos disponíveis

Hoje os eventos disponíveis para webhooks são os dos tokens de API:

Evento	Quando acontece
api_key.db.created	Um token foi criado — inclusive o token novo de uma rotação, que traz predecessor_id.
api_key.db.updated	Os dados de um token mudaram: nome, descrição, validade, e-mails de aviso ou status.
api_key.db.deleted	Um token revogado foi excluído da lista.
api_key.status_changed	O status de um token mudou (ativo, desabilitado ou revogado).
api_key.rotated	Um token foi rotacionado. Traz successor_id e grace_until, o fim do prazo em que o token antigo ainda vale.
api_key.revoked	Um token foi revogado.

Esses eventos acontecem quando os tokens são gerenciados no próprio Dashboard Mágico (veja Tokens de API). Os tokens criados na Conta Kobana não geram eventos aqui.

Formato do payload

Todo evento chega no mesmo envelope, em JSON com campos em snake_case:

{
  "id": "9f8b2c14-3a5d-4e77-9b10-2c6e5f0a1d33",
  "type": "api_key.status_changed",
  "created_at": "2026-10-05T10:30:00.000Z",
  "data": { },
  "changes": {
    "status": { "from": "active", "to": "disabled" }
  },
  "environment": "production",
  "version": "2026-03-01"
}

Campo	O que é
id	O ID do evento. Use-o para não processar o mesmo evento duas vezes.
type	O evento, como api_key.status_changed.
created_at	Quando o evento aconteceu, em ISO 8601 (UTC).
data	O recurso no estado atual, no mesmo formato da API.
changes	Só nos eventos *.status_changed: o que mudou, no formato {"campo": {"from": antigo, "to": novo}}.
environment	O ambiente que enviou, como production ou sandbox.
version	A versão do formato do payload. Campos novos podem aparecer; trate-os como opcionais.

O evento enviado por Testar Webhook tem type igual a test.webhook e um data com uma mensagem de teste. Ele serve para conferir a conexão e a assinatura; não trate como um evento real.

A referência completa — headers, assinatura e exemplos de código — está na referência de webhooks da API.