# Los webhooks

> Envía eventos de AI CodeOps a Slack, Discord, Teams o tu propio endpoint HTTPS, verifica las cargas firmadas y llama a tu pipeline de despliegue cuando se fusiona un cambio.

Fuente: https://aicodeops.dev/es/docs/webhooks · Última actualización: 2026-10-18

AI CodeOps envía webhooks hacia fuera; no los recibe. Puedes:

- enviar eventos del espacio de trabajo a un chat o a tu propio endpoint, con los **endpoints de notificación**;
- llamar a tu pipeline de despliegue cuando se fusiona un pull request de AI CodeOps, con los **webhooks de despliegue**.

## Sin webhooks entrantes de Git

Las sesiones no registran webhooks en tus repositorios. AI CodeOps trabaja con GitHub, GitLab, Bitbucket, Gitea y Forgejo a través de la cuenta que conectas, y comprueba el estado de un pull request preguntando a tu proveedor de Git. El único webhook que añade es el de un repositorio que conectas en **Build & Test → Builds**, para que un push o un pull request puedan iniciar un build. Un servidor Git autogestionado tampoco necesita ningún webhook entrante para las sesiones, pero AI CodeOps debe poder llegar a él: usa su dirección https pública (un servidor en una red privada solo funciona si el operador lo incluye en la lista de permitidos). Consulta [Conectar GitHub](https://aicodeops.dev/es/docs/git/github) y las demás guías de Git.

## Endpoints de notificación

### Añadir un endpoint

1. Abre **Configure → Settings** y busca **Notification endpoints**.
2. Elige **Add endpoint**.
3. Rellena:
   - **Name**: por ejemplo «Canal de Slack de guardia».
   - **Kind**: Slack, Discord, MS Teams o Generic webhook.
   - **Target URL**: la URL de webhook entrante de tu herramienta de chat, o tu propio endpoint.
   - **Min severity**: info (all), low+, medium+, high+ o critical only.
   - **Events to send**: marca los eventos que quieres. Si no marcas ninguno, se envían todos los eventos.
   - **Signing secret** (solo Generic webhook): 8 caracteres como mínimo.
4. Elige **Create endpoint**.

Los roles Owner, Admin y DevOps Admin pueden gestionar endpoints. Consulta [Roles y permisos](https://aicodeops.dev/es/docs/roles-and-permissions).

La URL de destino debe ser una dirección HTTPS pública. Las entregas a `localhost`, a redes privadas o a direcciones de metadatos de la nube se rechazan, y no se siguen las redirecciones.

### Eventos

| Evento             | Tipo                       | Cuándo                                                |
| ------------------ | -------------------------- | ----------------------------------------------------- |
| Deploy failed      | `deployment.failed`        | Un despliegue falló                                   |
| Deploy succeeded   | `deployment.completed`     | Un despliegue tuvo éxito                              |
| Deploy recorded    | `deployment.recorded`      | Cualquier registro de despliegue, en cualquier estado |
| Incidents & policy | `policy_decision.recorded` | Un incidente se abre o cambia, o una política decide  |
| Approval requested | `approval.requested`       | Una solicitud está esperando una decisión             |
| Approval decided   | `approval.decided`         | Una solicitud se aprobó o se rechazó                  |
| Run completed      | `workflow_run.completed`   | Una sesión terminó                                    |
| New finding        | `agent_finding.created`    | Una revisión planteó un hallazgo                      |
| Schedule failed    | `schedule.failed`          | Un flujo de trabajo programado no se pudo ejecutar    |

Si no hay ningún evento marcado, el endpoint recibe también las actualizaciones de progreso de las sesiones y de los pasos de agente.

**Min severity** filtra solo los eventos que llevan una gravedad, como los hallazgos, los incidentes y las programaciones fallidas. Los eventos que no la llevan se envían siempre.

### Cargas

Slack y Microsoft Teams reciben `{"text": "<summary>"}`. Discord recibe `{"content": "<summary>"}`. El resumen es una línea, por ejemplo:

```text
Deploy prj_01JA2B3C4D5E6F7G8H9J0K1M2R → production @ 3f9c2a1b: failed — The deploy webhook answered HTTP 502.
```

Un **Generic webhook** recibe el resumen y el evento como JSON, con `Content-Type: application/json`:

```json
{
  "summary": "Deploy prj_01JA2B3C4D5E6F7G8H9J0K1M2R → production @ 3f9c2a1b: failed — The deploy webhook answered HTTP 502.",
  "event": {
    "kind": "deployment.failed",
    "workspaceID": "wrk_01JA2B3C4D5E6F7G8H9J0K1M2N",
    "entityID": "dep_01JA2B3C4D5E6F7G8H9J0K1M2P",
    "workflowRunID": "wfr_01JA2B3C4D5E6F7G8H9J0K1M2Q",
    "status": "failed",
    "emittedAt": "2026-10-18T09:00:00.000Z",
    "metadata": {
      "projectID": "prj_01JA2B3C4D5E6F7G8H9J0K1M2R",
      "environment": "production",
      "sequence": 3,
      "commitSHA": "3f9c2a1b7d4e5f60718293a4b5c6d7e8f9012345",
      "strategy": "rolling",
      "errorSummary": "The deploy webhook answered HTTP 502."
    }
  }
}
```

Todos los eventos tienen `kind`, `workspaceID`, `entityID` y `emittedAt`. `workflowRunID`, `status` y `metadata` aparecen cuando corresponde. El evento es ligero: obtén los detalles en la consola si los necesitas.

### Verificar la firma

Un Generic webhook con un secreto de firma envía dos cabeceras:

```http
X-CodeOps-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with your secret>
X-CodeOps-Event: deployment.failed
```

Para verificarla, calcula el HMAC-SHA256 del cuerpo sin procesar de la petición con tu secreto y compáralo con la cabecera en tiempo constante. Por ejemplo, en Node.js:

```js
import { createHmac, timingSafeEqual } from "node:crypto"

function verify(rawBody, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}
```

Usa los bytes del cuerpo exactamente como se recibieron, antes de analizar el JSON. La firma no lleva marca de tiempo, así que, para descartar duplicados, usa `kind`, `entityID` y `emittedAt` juntos; `emittedAt` no cambia cuando se reintenta una entrega.

### Prueba, reintentos y el registro de entregas

Cada endpoint tiene **Test**, **Deliveries**, **Disable** y **Delete**.

- **Test** envía un evento de ejemplo de inmediato, sean cuales sean los filtros del endpoint.
- **Deliveries** muestra cada intento con su estado, el tipo de evento, el estado HTTP, el número de intento, la latencia y el detalle. El historial de entregas se conserva 30 días.
- Una entrega agota el tiempo a los 8 segundos. Los errores de red, los tiempos agotados y los HTTP 408, 425, 429, 500, 502, 503 y 504 se reintentan a los 30 segundos, a los 2 minutos y a los 8 minutos. Los demás errores no se reintentan.
- Después de 10 entregas fallidas seguidas, el endpoint se desactiva. Corrígelo y elige **Enable**.

Todavía no hay formulario de edición: para cambiar un endpoint, elimínalo y añádelo de nuevo.

## Webhooks de despliegue

Un webhook de despliegue llama a tu pipeline cuando un pull request de AI CodeOps se fusiona desde la consola.

1. Abre **Release → Deployments** y elige **Deploy targets**.
2. Para cada proyecto, introduce una **Deploy webhook URL**, un **Environment** y, si quieres, un **Signing secret**.
3. Guarda.

Al fusionar, AI CodeOps envía:

```json
{
  "event": "pr_merged",
  "workspaceID": "wrk_01JA2B3C4D5E6F7G8H9J0K1M2N",
  "projectID": "prj_01JA2B3C4D5E6F7G8H9J0K1M2R",
  "repo": "acme/api",
  "prNumber": 42,
  "prUrl": "https://github.com/acme/api/pull/42"
}
```

Con un secreto de firma añade `X-CodeOps-Signature: sha256=…`, calculado de la misma forma que arriba. La URL debe ser HTTPS pública. Una regla `release.deploy` de la [política del espacio de trabajo](https://aicodeops.dev/es/docs/policy-engine) puede bloquear los despliegues automáticos a un entorno.

## Siguientes pasos

- [API](https://aicodeops.dev/es/docs/api)
- [Referencia de las reglas de política](https://aicodeops.dev/es/docs/policy-engine)
- [Aprobaciones y políticas](https://aicodeops.dev/es/docs/approvals-and-policies)

## Preguntas frecuentes

### ¿Tengo que añadir un webhook a mi repositorio Git?

No para las sesiones, que hablan con tu proveedor de Git con el token de tu conexión. Solo un repositorio que conectas en Build & Test → Builds recibe un webhook, y AI CodeOps lo añade por ti, para que un push o un pull request puedan iniciar un build.

### ¿Las cargas de las notificaciones van firmadas?

Los webhooks genéricos con un secreto de firma se firman con HMAC-SHA256 en la cabecera X-CodeOps-Signature. Los mensajes de Slack, Discord y Teams no se firman.

### ¿Qué pasa si mi endpoint está caído?

Las entregas fallidas se reintentan a los 30 segundos, a los 2 minutos y a los 8 minutos. Después de 10 fallos seguidos, el endpoint se desactiva.
