> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/06-task-engine.md).

# Task Engine y Webhooks

VergeOS **Motor de tareas** es un marco de automatización integrado que permite operaciones impulsadas por eventos y por programación sin herramientas externas. En lugar de escribir scripts o depender de trabajos cron en máquinas separadas, los administradores definen tareas, adjuntan disparadores y dejan que la plataforma ejecute acciones automáticamente. El Motor de tareas es el complemento nativo de las herramientas de API e IaC cubiertas anteriormente en este módulo: donde Terraform y Ansible gestionan el aprovisionamiento, el Motor de tareas maneja la automatización operativa diaria dentro del sistema en ejecución.

## Componentes del Motor de tareas

El Motor de tareas utiliza seis bloques de construcción modulares que pueden componerse en combinaciones flexibles:

| Componente              | Descripción                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Tareas**              | Definen la acción a realizar (p. ej., apagar una VM, enviar una notificación)                                                      |
| **Programaciones**      | Especifican cuándo y con qué frecuencia debe ejecutarse una tarea (p. ej., diario, semanal, una sola vez)                          |
| **Eventos**             | Definen las condiciones que activan una tarea (p. ej., inicio de sesión de usuario, fallo de sincronización)                       |
| **Webhooks**            | Envía datos a sistemas externos mediante HTTP POST en tiempo real                                                                  |
| **Scripts**             | Bloques de construcción de automatización programables visibles en el Panel de tareas (consulte la sección Scripts a continuación) |
| **Registros de tareas** | Registran el historial de creación y ejecución de tareas para auditoría y solución de problemas                                    |

Todos los componentes se acceden desde **Sistema → Panel de tareas** en la interfaz de VergeOS.

```mermaid
flowchart LR
    subgraph Disparadores
        E[Disparador de evento<br/>inicio de sesión de usuario, error de sincronización]
        S[Disparador de programación<br/>diario, semanal, una sola vez]
    end

    subgraph Acciones
        T1[Tarea: Encender VM]
        T2[Tarea: Enviar correo electrónico]
        T3[Tarea: Enviar webhook]
    end

    subgraph Externo
        SL[Canal de Slack]
        EM[Correo electrónico / SMTP]
        ZP[Zapier / Supervisión]
    end

    E --> T1
    E --> T2
    E --> T3
    S --> T1
    S --> T2
    T3 --> SL
    T3 --> ZP
    T2 --> EM
```

## Arquitectura modular de automatización

Una fortaleza clave del Motor de tareas es su **muchos a muchos** modelo de relaciones. Los componentes no están limitados a emparejamientos uno a uno:

* **Múltiples tareas o eventos → un solo webhook** — Configure un webhook una vez y actívelo desde varios eventos diferentes (fallos de sincronización, intentos de inicio de sesión, alertas del sistema). Esto centraliza las integraciones externas y reduce la duplicación.
* **Una sola tarea → múltiples eventos** — Una tarea "Encender VM" puede activarse cuando un usuario específico inicia sesión *o* cuando comienza una ventana de mantenimiento programada. Reutilice las definiciones de tareas en distintos escenarios.
* **Una sola programación → múltiples tareas** — Defina una ventana de mantenimiento semanal una vez y vincúlela a tareas de actualización, alerta y apagado. Coherencia sin deriva de configuración.

Este diseño componible significa que usted crea una biblioteca de tareas, programaciones y webhooks reutilizables, y luego los conecta a medida que evolucionan sus necesidades operativas.

## Disparadores basados en eventos

Los disparadores de eventos activan tareas automáticamente cuando se detecta una ocurrencia específica del sistema. Al crear un evento, selecciona:

1. **Tipo** — La clase de objeto (p. ej., Usuarios, Máquinas virtuales, Alarmas, Tenants, Sincronizaciones salientes)
2. **Evento** — La ocurrencia específica (p. ej., Inicio de sesión, Cierre de sesión, Encendido, Error, Cambio de estado)
3. **Instancia de objeto o etiqueta** — Ya sea un objeto específico (un usuario o una VM concreta) o una etiqueta que coincida con un grupo de objetos

### Patrones comunes de disparadores de eventos

| Tipo de evento             | Evento de ejemplo                   | Acción típica                                                   |
| -------------------------- | ----------------------------------- | --------------------------------------------------------------- |
| Usuarios                   | Inicio de sesión / Cierre de sesión | Encender/apagar VMs con GPU para el usuario que inició sesión   |
| Sincronizaciones salientes | Error                               | Enviar notificación de Slack + alerta por correo electrónico    |
| Máquinas virtuales         | Encendido / Apagado                 | Registrar en un sistema externo de supervisión mediante webhook |
| Alarmas                    | Gravedad del error                  | Enviar notificación por correo al equipo de operaciones         |
| Alarmas                    | Generada                            | Enviar webhook a PagerDuty o a la rotación de guardia           |

{% hint style="success" %}
**Disparadores basados en etiquetas**

En lugar de crear eventos separados para cada VM, asigne una **etiqueta** (p. ej., `gpu-workstation`) compartida a las VMs relacionadas. Luego configure el disparador de evento para que coincida con esa etiqueta: cualquier VM con la etiqueta activará el disparador. Esto es mucho más fácil de mantener que los eventos por objeto.
{% endhint %}

## Disparadores basados en programación

Los disparadores de programación ejecutan tareas en momentos o intervalos predefinidos. VergeOS incluye varias programaciones predeterminadas y admite la creación de programaciones personalizadas.

### Opciones de configuración de programación

* **Recurrente** — Repetir cada N días, horas, minutos, semanas, meses o años, con selección específica de día y hora
* **Una sola vez** — Seleccione "No se repite" y especifique una única fecha y hora de inicio
* **Fecha de finalización** — Las programaciones recurrentes son perpetuas de forma predeterminada; opcionalmente establezca una fecha de finalización

### Patrones comunes de programación

| Programación              | Caso de uso                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| Cada sábado a las 5 PM    | Comprobar y descargar actualizaciones del sistema                             |
| Cada viernes a las 6 PM   | Apagar las VMs que consumen muchos recursos al final de la jornada            |
| Fecha futura específica   | Deshabilitar la cuenta de un empleado temporal 30 días después de su creación |
| Diariamente a medianoche  | Ejecutar comprobaciones de verificación de respaldo del tenant                |
| El primer día de cada mes | Generar informes de utilización de recursos                                   |

## Webhooks

Los webhooks permiten mensajería basada en envío a sistemas externos cuando se ejecutan tareas. En lugar de que los sistemas externos consulten VergeOS para obtener el estado, la plataforma envía proactivamente solicitudes HTTP POST a URL predefinidas cuando se cumplen las condiciones configuradas.

### Configuración del webhook

Al crear un webhook, configuras:

| Campo                                | Descripción                                                                        |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| **Nombre**                           | Identificador descriptivo del webhook                                              |
| **URL**                              | El extremo de la API en el sistema externo que acepta solicitudes HTTP POST        |
| **Tipo de autorización**             | Token Bearer, clave de API, Básica (nombre de usuario/contraseña) o Ninguna        |
| **Encabezados**                      | Encabezados HTTP personalizados (predeterminado: `content-type: application/json`) |
| **Permitir certificados no seguros** | Para certificados autofirmados en entornos de desarrollo/pruebas                   |
| **Tiempo de espera**                 | Máximo de segundos para esperar una respuesta (mínimo 3)                           |
| **Reintentos**                       | Número de nuevos intentos en caso de fallo o ausencia de respuesta                 |

### Variables de carga útil

Las cargas útiles de las tareas webhook admiten variables dinámicas que se resuelven en tiempo de ejecución:

| Variable       | Valor                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------- |
| `${DATE}`      | Fecha/hora actual en formato de cadena completa (p. ej., `Thu, 16 Oct 2025 11:38:07 EDT`) |
| `${TIMESTAMP}` | Fecha/hora actual como entero de época (p. ej., `1760629087`)                             |
| `${RANDOM}`    | Entero generado aleatoriamente                                                            |
| `${NAME}`      | Nombre del objeto VergeOS aplicable                                                       |

### Casos de uso de webhooks

* Enviar una **notificación de Slack** a un canal de administración cuando un trabajo de sincronización produce un error
* Publicar en un **sistema contable** cuando un tenant entra en línea, activando la facturación automática
* Activar un **flujo de trabajo de Zapier** cuando una VM específica se enciende, iniciando acciones entre aplicaciones

## Ejemplo práctico 1: Encendido/apagado automático de VMs con GPU

Este ejemplo demuestra cómo las etiquetas, tareas, eventos y programaciones trabajan juntas para gestionar cargas de trabajo de GPU intensivas en recursos.

**Escenario:** El usuario JThompson utiliza varias VMs con GPU para modelado 3D. Estas VMs consumen una cantidad significativa de cómputo y memoria, por lo que dejarlas ejecutándose cuando están inactivas es un desperdicio.

**Objetivo:** Encender las VMs cuando JThompson inicie sesión, apagarlas al cerrar sesión y aplicar como medida de seguridad un apagado los viernes a las 6 PM.

### Pasos de configuración

1. **Crear una etiqueta** — En Sistema → Etiquetas, cree una categoría `VMs` con una etiqueta `JThompson-GPU`. Asigne esta etiqueta a las VMs de destino.
2. **Crear tarea "Encender"** — Sistema → Panel de tareas → Nueva tarea. Establezca el tipo de objeto en `Máquinas virtuales`, seleccione la etiqueta `JThompson-GPU`, y establezca la acción en `Encender`.
3. **Agregar disparador de evento de inicio de sesión** — Desde el panel de tareas, agregue un disparador de evento: Tipo = `Usuarios`, Evento = `Inicio de sesión`, Objeto = `JThompson`.
4. **Crear tarea "Apagar"** — Nueva tarea con la misma selección de etiqueta, pero Acción = `Apagar`.
5. **Agregar disparador de evento de cierre de sesión** — Disparador de evento en la tarea de apagado: Tipo = `Usuarios`, Evento = `Cierre de sesión`, Objeto = `JThompson`.
6. **Crear programación para el viernes** — Nueva programación: Repetir cada 1 semana los viernes a las 6:00 PM.
7. **Agregar disparador de programación** — Adjunte la programación del viernes a la tarea "Apagar" como disparador de programación.

**Resultado:** Las VMs se encienden automáticamente cuando JThompson inicia sesión, se apagan al cerrar sesión y se garantiza que se apaguen todos los viernes a las 6 PM, independientemente del estado de inicio de sesión. Este patrón se aplica a cualquier carga de trabajo de alto consumo de recursos: equipos de entrenamiento de ML, estaciones de renderizado CAD, entornos de pruebas de integración o clústeres de modelado financiero.

## Ejemplo práctico 2: Alerta de Slack + correo electrónico ante error de sincronización

Este ejemplo muestra cómo los webhooks, las tareas y los eventos se combinan para proporcionar alertas multicanal para operaciones de DR/BC.

**Escenario:** Un proveedor de servicios necesita una notificación inmediata cuando los trabajos de sincronización nocturnos encuentren errores, tanto por Slack como por correo electrónico.

### Pasos de configuración

1. **Crear un webhook** — Sistema → Panel de tareas → Nuevo webhook. Configure la URL del webhook entrante de Slack, establezca el tipo de autorización en `Token Bearer` con el token del bot de Slack, y establezca content-type en `application/json`.
2. **Crear tarea de correo electrónico** — Nueva tarea: Tipo de objeto = `Correo electrónico`, configure la dirección del destinatario y el cuerpo del mensaje de alerta.
3. **Crear tarea de webhook** — Nueva tarea: Tipo de objeto = `Webhook`, seleccione el webhook de Slack, Acción = `Enviar`. Defina la carga útil JSON:

   ```json
   {
     "text": "Alerta de error de sincronización: ${NAME} falló en ${DATE}"
   }
   ```
4. **Agregar disparador de evento a la tarea de webhook** — Tipo = `Sincronizaciones salientes`, Evento = `Error`, seleccione el trabajo de sincronización específico (o use una etiqueta para varias sincronizaciones).
5. **Agregar el mismo disparador de evento a la tarea de correo electrónico** — Misma configuración que en el paso 4, vinculándola a la tarea de correo electrónico.

**Resultado:** Cuando cualquier trabajo de sincronización supervisado produce un error, tanto el canal de Slack como la bandeja de entrada de correo reciben alertas simultáneamente. Los administradores pueden investigar rápidamente, maximizando la posibilidad de completar la sincronización dentro de la ventana disponible.

{% hint style="success" %}
**Escalar con etiquetas**

Si desea que el mismo disparador se aplique a todas las sincronizaciones salientes, asigne una etiqueta compartida (p. ej., `critical-sync`) a esos trabajos de sincronización. Configure el disparador para activarse con cualquier sincronización que tenga esa etiqueta; no es necesario crear disparadores individuales por sincronización.
{% endhint %}

## Crear tareas: referencia rápida

Cada tarea sigue el mismo patrón de creación:

1. Vaya a **Sistema → Panel de tareas → Nueva tarea**
2. Configurar: **Nombre**, **Tipo de objeto**, **Objeto** (instancia específica o etiqueta), **Acción**, **Configuración**
3. Adjunte uno o más **Disparadores de eventos** y/o **Disparadores de programación**
4. Verifique en **Registros de tareas** que la tarea se active correctamente

Las tareas tienen un **Habilitado** indicador; puede deshabilitar temporalmente una tarea si necesita verificar la configuración antes de activarla, y luego volver a habilitarla cuando esté lista.

### Campos de la tarea

**Nombre** — Identificador descriptivo **Tipo de objeto** — Sección de la aplicación (VMs, Redes, Usuarios, Webhooks, etc.) **Objeto** — Objetivo específico o etiqueta **Acción** — Operación a realizar **Eliminar después de ejecutarse** — Opción de ejecución única

### Registros de tareas

Cada ejecución de tarea se registra con: - marca de tiempo y duración - estado de éxito/fallo - evento o programación que la activó - detalles del objeto de destino Los registros están disponibles desde el Panel de tareas para auditoría.

## Scripts (vista previa)

La **Scripts** La característica, introducida en VergeOS 26, sienta las bases para futuros flujos de trabajo de automatización definidos por el administrador. Aunque actualmente está reservada para las operaciones internas del sistema, ha sido diseñada pensando en la extensibilidad. Las versiones futuras ampliarán Scripts para admitir automatización personalizada del administrador directamente dentro de la plataforma, complementando el Motor de tareas existente con lógica programable.

{% hint style="info" %}
**¿Vienes de VMware o Nutanix?**

El Motor de tareas está integrado en VergeOS en todos los niveles (incluidos los tenants): no hay ningún dispositivo orquestador separado ni una licencia adicional de automatización. Configure disparadores de eventos, programaciones y webhooks desde la misma interfaz que ya usa para VMs y almacenamiento.
{% endhint %}

## Puntos clave

### Impulsado por eventos

Active la automatización a partir de eventos del sistema — inicio/cierre de sesión de usuario, errores de sincronización, cambios de estado de VM, condiciones de alarma — sin sondeo ni programadores externos.

### Impulsado por programación

Ejecute tareas en momentos específicos usando programaciones integradas o personalizadas. Una sola vez o recurrentes, con fechas de finalización opcionales.

### Integración externa

Envíe notificaciones a Slack, correo electrónico, Zapier o cualquier extremo HTTP mediante webhooks con autenticación, encabezados y lógica de reintento configurables.

### Modular y reutilizable

Relaciones muchos a muchos entre tareas, eventos, programaciones y webhooks. Construya una vez, componga libremente.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/es/modulo-8-desarrollador-y-devops/06-task-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.