Eventos de webhook

Un evento es el registro de algo que ocurrió en la organización — un token creado, un token revocado. Al registrar un endpoint, marcas los eventos que quiere recibir; cada vez que ocurre uno de ellos, Dashboard Mágico envía una entrega al endpoint.

Eventos disponibles

Hoy los eventos disponibles para webhooks son los de los tokens de API:

Evento	Cuándo ocurre
api_key.db.created	Se creó un token — incluido el token nuevo de una rotación, que trae predecessor_id.
api_key.db.updated	Cambiaron los datos de un token: nombre, descripción, vencimiento, correos de aviso o estado.
api_key.db.deleted	Un token revocado se quitó de la lista.
api_key.status_changed	Cambió el estado de un token (activo, deshabilitado o revocado).
api_key.rotated	Se rotó un token. Trae successor_id y grace_until, el fin del plazo en que el token anterior todavía vale.
api_key.revoked	Se revocó un token.

Estos eventos ocurren cuando los tokens se gestionan en el propio Dashboard Mágico (mira Tokens de API). Los tokens creados en la Cuenta Kobana no generan eventos aquí.

Formato del payload

Todo evento llega en el mismo sobre, en JSON con campos en 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	Qué es
id	El ID del evento. Úsalo para no procesar el mismo evento dos veces.
type	El evento, como api_key.status_changed.
created_at	Cuándo ocurrió el evento, en ISO 8601 (UTC).
data	El recurso en su estado actual, en el mismo formato de la API.
changes	Solo en los eventos *.status_changed: qué cambió, en el formato {"campo": {"from": anterior, "to": nuevo}}.
environment	El ambiente que envió, como production o sandbox.
version	La versión del formato del payload. Pueden aparecer campos nuevos; trátalos como opcionales.

El evento enviado por Test Webhook tiene type igual a test.webhook y un data con un mensaje de prueba. Sirve para comprobar la conexión y la firma; no lo trates como un evento real.

La referencia completa — headers, firma y ejemplos de código — está en la referencia de webhooks de la API.