# Webhooks

> Avisos automáticos a tu sistema cuando algo ocurre en la plataforma: eventos, filtros, datos personales, historial de envíos y fallos del destino.

Un webhook avisa a tu sistema cuando algo ocurre en la plataforma. Por ejemplo: un alumno concluyó una clase, y Cademí envía un aviso a tu CRM. El webhook es la dirección de tu sistema (o de Zapier, Make, n8n) que recibe esos avisos. Configuras todo en **Configuraciones > Webhooks**. El formato de cada evento, para quien va a programar el receptor, está en https://cademi.dev/webhooks.

## La idea en un minuto

- Un **evento** es un hecho que Cademí registra en la cuenta: un alumno recibió acceso, aprobó un examen, concluyó una clase.
- Un **webhook** es una dirección inscrita en algunos eventos.
- Una **entrega** es cada aviso que Cademí envía a esa dirección.

Una entrega de webhook no tiene relación con una entrega de ventas ([Entregas](/es/vendas/entregas)).

**La regla más importante:** el webhook escucha el acceso, no la venta. Una venta del gateway no es un evento. Lo que llega a tu sistema es el acceso que produjo la venta.

La pantalla tiene dos pestañas:

- **Endpoints**: la lista de los webhooks. Cada fila muestra **Evento / alcance**, **Endpoint** y **Estado**. El **Estado** es **Activo** o **Inactivo**, y lo cambias en la misma fila. Los filtros **Eventos** y **Estado** y la búsqueda por dirección recortan la lista.
- **Historial**: las entregas.

Hay dos formatos de webhook:

- **Cademí v3**, el formato actual. Un webhook recibe varios eventos, cada uno con su filtro, y cada envío va firmado. Es lo que crea **Nuevo webhook**, y es lo que explica este artículo.
- **Heredado v2** y **Heredado v1 (descontinuado)**, el formato antiguo, con un evento por webhook. Sirve solo para un sistema que ya recibe ese formato. **Nuevo webhook heredado** crea uno. En una integración nueva, usa **Nuevo webhook**.

## Crear un webhook

1. Abre **Configuraciones > Webhooks**.
2. Haz clic en **Nuevo webhook**.
3. En **A dónde enviar**, pega el **Endpoint**: la dirección de tu sistema, que empieza con https://.
4. Si quieres, completa la **Descripción**. Te ayuda a reconocer el webhook en la lista y no va en el envío.
5. En **Cuándo enviar**, marca los eventos.
6. En los eventos que aceptan filtro, completa el bloque **Enviar solo cuando**, que aparece justo debajo. Vacío quiere decir "siempre que ocurra".
7. En **Qué lleva cada envío**, elige el nivel de datos personales (mira abajo).
8. Revisa el **Resumen**, al lado.
9. Haz clic en **Crear webhook**.
10. En la ventana **Secreto de firma**, copia y guarda el secreto.

El secreto no aparece de nuevo. Con él, tu servidor comprueba que cada envío salió de Cademí.

Para elegir los eventos, la pantalla tiene dos pestañas:

- **Recorrido del alumno** agrupa los momentos más usados.
- **Sincronización (avanzado)** lista todos los eventos de la plataforma, por grupo, con el nombre técnico. Es para quien mantiene otro sistema siempre al día con Cademí.

**Buscar evento** busca en las dos pestañas. **Marcar todos** y **Desmarcar** valen por grupo. **Ver ejemplo del envío** muestra lo que llega a tu dirección, con datos de ejemplo.

### Los momentos del recorrido del alumno

| Momento | Eventos |
|---|---|
| **Registro** | **Alumno creado**, **Etiquetas del alumno actualizadas**, **Campo personalizado actualizado** |
| **Acceso** | **Acceso liberado**, **Primer acceso**, **Acceso suspendido o reactivado**, **Acceso revocado**, **Acceso restaurado** |
| **Progreso** | **Curso iniciado**, **Clase concluida**, **Hito de progreso alcanzado**, **Progreso actualizado**, **Curso concluido** |
| **Exámenes** | **Examen concluido**, **Intento de examen reabierto** |
| **Certificados** | **Certificado emitido**, **Certificado revocado** |
| **Términos** | **Término aceptado** |
| **Puntos** | **Puntos acreditados**, **Puntos ajustados** |
| **Atención** | **Ticket abierto**, **Ticket respondido**, **Ticket cerrado**, **Duda enviada**, **Duda respondida**, **Comentario enviado**, **Comentario respondido** |

**Atención: aquí es donde ocurren más errores.** Cada evento tiene su momento exacto:

- Venta: el alumno recibe una entrega y dispara **Acceso liberado**. El reembolso, el atraso y el pago de vuelta disparan **Acceso suspendido o reactivado**.
- **Curso iniciado** es la primera clase concluida, no el acceso concedido. Para la bienvenida, usa **Alumno creado** o **Primer acceso**.
- **Examen concluido** dispara con aprobado o reprobado. Para solo uno de ellos, filtra por **Resultado del examen**.
- Llegar al 100% no emite certificado. **Certificado emitido** solo ocurre cuando alguien pide el certificado.
- El aviso de un comentario o de una duda no lleva el texto que escribió el alumno.
- Un administrador que ve el área como alumno de prueba no genera ninguno de esos eventos.

### Los filtros

| Filtro | En los eventos de | Qué hace |
|---|---|---|
| **Producto** | progreso, exámenes, certificados, comentarios y dudas | Un solo producto, o **Cualquier producto** |
| **Clase** y **Examen** | clase concluida, comentarios, dudas y exámenes | Aparecen después de que eliges el producto. Puedes marcar varias |
| **Resultado del examen** | **Examen concluido** | **Aprobado o reprobado**, **Solo aprobado** o **Solo reprobado** |
| **Al llegar a** | **Hito de progreso alcanzado** | 50%, 75% o 90% |
| **A partir de** | **Progreso actualizado** | Un porcentaje mínimo. Después de que el alumno lo supera, cada clase siguiente dispara de nuevo. Para un aviso único, prefiere el hito |
| **Tipo de registro** | **Alumno creado** | **Registro pago** o **Registro gratuito**. El registro con Google y el de la importación no son ni uno ni otro. Con una de las dos opciones, quedan fuera |
| **Oferta** | **Acceso liberado** | Solo los accesos de esa entrega: los compradores de esta oferta |
| **Etiqueta que recibió el alumno** | **Etiquetas del alumno actualizadas** | Solo cuando se agrega esa etiqueta. Una etiqueta que el alumno ya tenía, o que solo se quitó, no dispara |
| **Campo personalizado** y **Solo cuando quede completado** | **Campo personalizado actualizado** | Un campo. Si quieres, solo cuando deja de estar vacío |
| **Término** | **Término aceptado** | Un término específico |
| **Puntos por** | **Puntos acreditados** | El motivo de los puntos (clase, hito, examen, comentario) |

### Cuántos datos personales van

El nivel vale para todos los eventos del mismo webhook.

| Nivel | Qué llega | Úsalo cuando |
|---|---|---|
| **Solo identificadores, sin datos personales** (el predeterminado) | Los códigos del alumno y de lo que ocurrió, sin nombre ni contacto. Tu sistema busca el resto por la API | El receptor consulta al alumno, o solo necesita contar |
| **Con datos personales enmascarados** | Los códigos, más nombre, correo y teléfono ocultos en parte. Sigue siendo dato personal | La herramienta necesita una pista de quién es, sin guardar el contacto real |
| **Completo, con datos personales** | Los datos tal como están en el registro | El sistema necesita escribir, llamar o facturar al alumno. Y es confiable para guardar esos datos |

Solo un administrador autorizado a ver los datos de los alumnos puede elegir el nivel completo. Si el webhook incluye tickets, también necesita ver la atención. Cademí revisa cada envío contra quien creó el webhook. Si esa persona pierde la autorización, los envíos salen enmascarados hasta que la recupere, y la pantalla lo avisa.

## La página de un webhook

Haz clic en la fila para abrir el webhook. Arriba están el estado, **Ver historial de este webhook**, **Enviar prueba** y **Generar nuevo secreto**.

El panel de salud muestra:

- el **Último envío entregado**;
- las **Últimas 24 horas**: entregados, fallos y en cola;
- el estado de la **Dirección**: **Recibiendo normalmente**, **Envíos pausados por fallos seguidos** o **Probando la dirección de nuevo**.

**Enviar prueba** envía ahora a tu dirección un ejemplo del evento elegido. El ejemplo tiene datos ficticios, va firmado con el secreto actual y se marca como prueba. Ves el **Estado HTTP**, el **Tiempo** y la **Respuesta**. La prueba no entra en el historial y no cuenta para la salud del webhook.

**Generar nuevo secreto** crea un secreto nuevo y lo muestra una vez. El anterior sigue firmando durante 24 horas. Así, cambias el secreto en el receptor sin interrupción.

## Historial

La pestaña **Historial** lista las entregas de los últimos 60 días, en cuatro vistas: **Todos**, **Éxito**, **Pendientes** y **Con error**. Solo **Con error** tiene conteo, porque es la cola que pide acción. El filtro **Webhook** recorta por destino.

Cada fila muestra **Enviado el**, **Evento**, **Código** (la respuesta del destino), **Endpoint** y **Estado**. Si hubo más de un intento, la fila muestra el número.

| Estado | Qué quiere decir |
|---|---|
| **En cola** | Esperando el próximo envío |
| **Enviando** | Saliendo ahora |
| **Éxito** | El destino recibió y respondió con éxito |
| **Error** | El destino rechazó de una forma que no sirve repetir (dirección inexistente o bloqueada). Solo sale de nuevo con un reenvío manual |
| **Agotado** | Los intentos se acabaron sin éxito. Solo sale de nuevo con un reenvío manual o al reactivar el webhook |
| **Cancelado** | Ya no se va a enviar. El webhook se desactivó o se eliminó antes de que saliera, o el sistema abandonó la dirección |

Haz clic en la fila para abrir **Detalles de la entrega**. La ventana muestra la **Respuesta** del destino y el **Payload** enviado. En las entregas que fallaron, tiene el botón **Reenviar**. Reenviar pone la misma entrega en la cola de nuevo. No crea un evento nuevo.

## Cuando el destino falla

Si la dirección no acepta una entrega, Cademí lo intenta de nuevo por sí sola:

- La espera entre los intentos crece de 2 minutos hasta 6 horas.
- Cademí lo intenta unas 10 veces, o durante 72 horas.
- Si el destino pide esperar, o está inestable, el aplazamiento no gasta intento.
- Un rechazo definitivo no se repite.

El camino de una entrega hasta el estado final, con los nuevos intentos y las vueltas a la cola:

```mermaid
stateDiagram-v2
    accTitle: El camino de una entrega de webhook
    accDescr: Cuando ocurre un evento marcado, la entrega entra en la cola y sale. Si el destino la acepta, queda en Éxito. Un fallo pasajero la devuelve a la cola para un nuevo intento. Un rechazo definitivo lleva a Error, y el fin de los intentos o del plazo lleva a Agotado. Desactivar o eliminar el webhook antes del envío lleva a Cancelado. Reenviar, o reactivar y reenviar, devuelve la entrega a la cola.
    state "En cola" as Fila
    state "Enviando" as Enviando
    state "Éxito" as Sucesso
    state "Error" as Erro
    state "Agotado" as Esgotado
    state "Cancelado" as Cancelado
    [*] --> Fila: Ocurre un evento marcado
    Fila --> Enviando
    Enviando --> Sucesso: El destino acepta
    Enviando --> Fila: Fallo pasajero, nuevo intento
    Enviando --> Erro: Rechazo definitivo
    Enviando --> Esgotado: Fin de los intentos o del plazo
    Fila --> Cancelado: Webhook desactivado por el sistema o eliminado
    Erro --> Fila: Reenviar
    Esgotado --> Fila: Reenviar, o reactivar y reenviar
    Cancelado --> Fila: Reactivar y reenviar
```

Con el webhook **Inactivo**, la entrega espera en la cola y no se cancela. Reactivar y reenviar devuelve solo lo que se agotó o se canceló por la desactivación en las últimas 48 horas. Una entrega cancelada porque se eliminó el webhook no vuelve.

| Situación | Qué ocurre | Cómo vuelve |
|---|---|---|
| Dejas el webhook **Inactivo** | Las entregas quedan retenidas. Esperar no es un fallo | Actívalo de nuevo y salen |
| La dirección falla en varios envíos diferentes en 24 horas | El sistema desactiva el webhook y cancela lo que todavía esperaba. Avisa por correo a los administradores que gestionan webhooks | En la página del webhook, **Reactivar** o **Reactivar y reenviar las últimas 48 horas** |
| La dirección pasa mucho tiempo sin responder | Todo webhook que apunta a esa dirección se desactiva. Esto vale también en otras cuentas que la usan | Reactiva cada uno |

La lista y la página del webhook muestran el motivo de la desactivación. Guardar el webhook no lo reactiva. Corrige la dirección, si hace falta, y usa **Reactivar**. Nada con más de 48 horas vuelve por sí solo.

## Para tener en cuenta

- **El receptor tiene que tolerar la repetición.** Los reenvíos y las reactivaciones entregan el mismo evento de nuevo. Si tu sistema no reconoce el evento repetido, un CRM crea dos contactos y una herramienta de correo le escribe dos veces al alumno.
- **Eliminar cancela lo que esperaba.** Eliminar un webhook cancela las entregas pendientes. Las concluidas quedan en el historial. El soporte puede recuperar el webhook eliminado.
- **Cambiar el nivel no reescribe el pasado.** Un nivel más completo vale para lo que ocurre después. Lo que ya se preparó sale como estaba.
- **El webhook no es un historial.** Se puede pausar y desactivar. Para mirar hacia atrás o armar un informe, usa la lista de eventos de la API, no un webhook en una hoja de cálculo.
- **Diamante.** Los mensajes de etapa de los embudos Diamante están en las pantallas de Diamante ([Embudos Diamante](/es/conteudo/funis-diamante)), no aquí.
- **Antiguo y nuevo en el mismo sistema.** Un webhook heredado y un webhook v3 que apuntan a la misma herramienta avisan el mismo momento dos veces, con dos nombres.

## Preguntas frecuentes

**Quiero avisar a mi CRM en cada compra.** En el momento **Acceso**, marca **Acceso liberado** y **Acceso suspendido o reactivado**. Si es una entrega específica, filtra por **Oferta**. El webhook escucha el acceso, no la venta.

**El evento ocurrió y no llegó nada.** Abre el **Historial** y busca la entrega:

- **En cola**: la plataforma todavía lo va a intentar.
- **Error** o **Agotado**: mira la **Respuesta** del destino, corrige y reenvía.
- Ninguna entrega: el evento no está marcado, o el filtro excluyó el caso.

Si la lista muestra el webhook desactivado, reactívalo.

**Mi webhook se desactivó solo.** La dirección falló en varios envíos seguidos. Corrige el destino y prueba con **Enviar prueba**. Después, haz clic en **Reactivar y reenviar las últimas 48 horas** para recuperar lo que quedó atrás.

**Recibí el mismo aviso dos veces.** Un reenvío o una reactivación entrega el mismo evento de nuevo. Tu sistema tiene que reconocer el evento repetido.