- Inicio
- Documentación
- Los webhooks
Los webhooks
Última actualización
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.
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 y las demás guías de Git.
Endpoints de notificación
Añadir un endpoint
- Abre Configure → Settings y busca Notification endpoints.
- Elige Add endpoint.
- 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.
- Elige Create endpoint.
Los roles Owner, Admin y DevOps Admin pueden gestionar endpoints. Consulta Roles y permisos.
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:
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:
{
"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:
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:
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.
- Abre Release → Deployments y elige Deploy targets.
- Para cada proyecto, introduce una Deploy webhook URL, un Environment y, si quieres, un Signing secret.
- Guarda.
Al fusionar, AI CodeOps envía:
{
"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 puede bloquear los despliegues automáticos a un entorno.
Siguientes pasos
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.