Webhooks

Un webhook es un aviso que Dashboard Mágico envía a tu sistema cuando algo ocurre — por ejemplo, cuando se revoca un token de API. En lugar de que tu sistema pregunte cada cierto tiempo, recibe un POST con los datos del evento apenas el evento ocurre. La dirección que recibe ese POST es el endpoint.

Los endpoints están en la pestaña Webhooks de Sistema › API (/dashboard/api?tab=webhooks).

Arriba, cuatro números resumen el workspace: endpoints Active e Inactive, Total Deliveries y Failed. Debajo viene la Webhooks List, con filtro por estado y búsqueda por URL, y después los Delivery Logs.

Endpoints y workspaces

Cada endpoint pertenece al workspace en que fue creado, y la lista muestra solo los del workspace activo. Los eventos de un workspace llegan únicamente a sus endpoints; los eventos de la organización como un todo llegan a los endpoints de todos los workspaces.

Crear un endpoint

1. En la Webhooks List, haz clic en New Webhook.

2. Completa los campos:

   Campo	Qué es
   Endpoint URL	La dirección que recibe los eventos. Tiene que ser https:// y pública: las direcciones internas o privadas (como localhost) se rechazan.
   Authentication	Una credencial que Dashboard Mágico envía en cada solicitud, si tu endpoint la exige: None, Basic Auth (usuario y contraseña), Bearer Token o Custom Header (nombre y valor). Se guarda cifrada.
   Description (optional)	Para recordar quién usa el endpoint — por ejemplo, ERP — actualizaciones de portal y usuarios.
   Events	Los eventos que el endpoint quiere recibir. Select all selecciona los de una categoría de una vez. Mira Eventos de webhook.

3. Haz clic en Create Webhook.

4. Dashboard Mágico muestra el secret del endpoint. Cópialo y guárdalo en un lugar seguro: no vuelve a aparecer. Haz clic en Saved.

Marca al menos un evento: el endpoint recibe solo los eventos marcados.

Qué se puede hacer con un endpoint

Dónde	Acción	Qué pasa
Columna Status	Interruptor encender/apagar	Apagado, el endpoint deja de recibir eventos. Enciéndelo de nuevo cuando quieras.
Columna Deliveries	Clic en el número	Abre el historial de entregas de ese endpoint.
Menú ⋯	View	Muestra la URL, la autenticación y los eventos.
Menú ⋯	Edit	Cambia la autenticación, la descripción y los eventos. La URL no cambia: para otra dirección, crea otro endpoint. Para cambiar una credencial, complétala de nuevo.
Menú ⋯	Test Webhook	Envía un evento de prueba (test.webhook), firmado como los reales, y muestra si el endpoint respondió con éxito. La prueba aparece en los logs de entrega.
Menú ⋯	Rotate Secret	Genera un secret nuevo, que se muestra una sola vez. El anterior deja de valer en el acto: actualiza tu sistema enseguida.
Menú ⋯	Delete	Elimina el endpoint y su historial de entregas. No hay vuelta atrás.

Cómo tu sistema comprueba que el aviso es de Dashboard Mágico

Cada entrega se firma con el secret del endpoint. Tu sistema recalcula la firma con el mismo secret y compara: si coincide, el aviso vino realmente de Dashboard Mágico y no fue alterado en el camino.

La firma sigue el estándar Standard Webhooks y va en los headers webhook-signature y X-Kobana-Signature. En resumen, tu sistema debe:

1. Leer los headers webhook-id, webhook-timestamp y webhook-signature.
2. Rechazar la entrega si la hora está a más de 5 minutos del reloj actual.
3. Calcular el HMAC-SHA256 de webhook-id + . + webhook-timestamp + . + el cuerpo exactamente como se recibió, con la clave del secret.
4. Comparar el resultado con la firma recibida.

El paso a paso, con ejemplos en Node.js y Python y la lista completa de headers, está en la referencia de webhooks de la API.

Desactivación automática

Si un endpoint falla 10 veces seguidas, Dashboard Mágico lo apaga solo, para no seguir insistiendo. Corrige el problema en tu sistema, usa Test Webhook para comprobar y enciende de nuevo el interruptor de la columna Status. Una entrega exitosa pone a cero el conteo de fallas.

Toda creación, modificación, prueba, rotación de secret y eliminación de un endpoint queda registrada en Auditoría.