Webhook, GitHub y GitLab

Dispara una automatización con una llamada HTTP firmada: registro en la pantalla y por la CLI, URL, secreto, curl, GitHub, GitLab, respuestas y rotación del secreto.

Ver Markdown

Traducción asistida por IA · idioma: ES · fuente: pt-br/fluxos/automacoes-webhook.md · fuenteHash: sha256:2b509d370ae030916e4236a4ad2ce8aa6870b5cae6dd61fadcc568b3030c71dc · revisión humana pendiente.

Un webhook permite que otro sistema dispare una automatización: GitHub cuando se abre un PR, GitLab cuando falla un pipeline, tu script de despliegue cuando termina. El sistema de origen hace una llamada HTTP POST a una URL de la automatización, firmada con un secreto que solo tú y Elyra conocen.

Hay tres formas de usarlo, y las tres comparten URL y secreto:

Disparador	Para qué	Cómo prueba la llamada quién es
Webhook (genérico)	Tus scripts, tu CI, cualquier sistema	Cabecera `X-Elyra-Signature-256`
GitHub	Eventos de un repositorio de GitHub	Cabecera `X-Hub-Signature-256` (el estándar de GitHub)
GitLab	Eventos de un proyecto de GitLab	Cabecera `X-Gitlab-Token` (el estándar de GitLab)

Qué tiene que estar en pie

Elyra Cloud activo en este computador. El Cloud es quien recibe la llamada que viene de internet. Sin él, los disparadores GitHub o GitLab y Webhook aparecen como Requiere Elyra Cloud activo y no se pueden elegir; por la CLI, el comando se niega con “GitHub, GitLab, and webhook triggers require an active Elyra Cloud server.”
El sistema de origen debe poder alcanzar la dirección de tu Cloud. La URL es pública, con el formato https://<tu-usuario>-cloud.elyra.sh/hooks/<id-de-la-automatización>.
La bóveda del sistema disponible. El secreto se guarda cifrado por el llavero del sistema operativo. Si no está disponible, Elyra se niega a crear el secreto y dice el motivo, en vez de guardarlo sin protección.

Si el Cloud está apagado cuando llega la llamada, Elyra no guarda cola: GitHub, GitLab o tu sistema tiene que reenviar.

Los disparadores que dependen del Cloud aparecen como “Requiere Elyra Cloud activo” mientras el Cloud no está activo

Registrarlo en la pantalla, paso a paso

Abre Automatizaciones > Crear automatización.
Ponle un nombre, por ejemplo “Avisar cuando termine un despliegue”.
En cuando esto ocurra, elige Webhook (o GitHub o GitLab, para los proveedores).
- Para GitHub o GitLab: elige el proveedor, indica el repositorio como propietario/nombre (por ejemplo empresa/proyecto) y marca los eventos.
Elige en (proyecto), en (workspace) y la cadena de acciones en haz esto. Mira Acciones.
Crear automatización.
Abre el detalle de la automatización. Allí están:
- Copiar URL: la dirección que llamará el sistema de origen;
- Copiar secreto: el secreto, mostrado una sola vez;
- Rotar secreto y Revocar secreto.
Copia el secreto enseguida y guárdalo en el sistema de origen. No vuelve a mostrarse cuando salgas de la pantalla. Si lo perdiste, usa Rotar secreto para generar otro.
Pega la URL y el secreto en el sistema de origen (mira las secciones de abajo) y dispara una prueba.

Cuando llegue el evento, la ejecución aparece en el Historial de la automatización, con “disparada porque…”.

Registrarlo por la CLI

La CLI crea la automatización, genera el secreto e imprime la URL y el secreto una vez.

Los ejemplos usan comillas simples, las de bash, zsh y Git Bash. En PowerShell y en cmd, las comillas internas del JSON necesitan escape; si el comando dice que el JSON es inválido, es eso.

Webhook genérico

elyra automations create \
  --name "Avisar cuando termine un despliegue" \
  --trigger daily --prompt "Despliegue terminado" --provider codex \
  --repo mi-proyecto \
  --trigger-json '{"kind":"webhook"}' \
  --actions '[{"kind":"notify","title":"Despliegue terminado","body":"El sistema de despliegue avisó que terminó"}]'

La salida trae, además del resumen de la automatización:

Webhook URL: https://<tu-usuario>-cloud.elyra.sh/hooks/<id-de-la-automatización>
Webhook secret (copy now): <secreto mostrado solo esta vez>

--trigger, --prompt y --provider siguen siendo obligatorios aun con --trigger-json: en los disparadores que no son un horario, son el texto que leen las versiones antiguas de Elyra. La cadena que vale es la de --actions.

GitHub

elyra automations create \
  --name "Revisar PR nuevo" \
  --trigger daily --prompt "Revisar PR" --provider codex \
  --repo mi-proyecto \
  --trigger-json '{"kind":"git-remote","provider":"github","repo":"empresa/proyecto","events":["pr-opened"]}' \
  --actions '[{"kind":"run-agent-in-workspace","prompt":"Revisa el PR que acaba de abrirse","agentId":"codex","workspaceMode":"new_per_run"}]'

GitLab

elyra automations create \
  --name "Investigar pipeline" \
  --trigger daily --prompt "Investigar pipeline" --provider codex \
  --repo mi-proyecto \
  --trigger-json '{"kind":"git-remote","provider":"gitlab","repo":"grupo/proyecto","events":["ci-failed"]}' \
  --actions '[{"kind":"notify","title":"El pipeline falló","body":"Mira GitLab"}]'

Los events aceptados en git-remote son pr-opened, pr-merged, review-requested, ci-failed e issue-opened. El repo debe tener la forma propietario/nombre. Los campos de cada acción están en Acciones.

Llamar al webhook genérico

La URL acepta solo POST, con un cuerpo JSON (un objeto) de hasta 1 MiB.

Cabecera	Valor	Obligatoria
`X-Elyra-Signature-256`	`sha256=` seguido del HMAC-SHA256, en hexadecimal, del cuerpo exacto, usando el secreto como clave	Sí
`X-Elyra-Event`	Nombre del evento, solo para el historial. Sin ella, vale el campo `event` del cuerpo; sin ambos, `webhook`	No
`Content-Type`	`application/json`	Recomendada

Ejemplo con curl, firmando el cuerpo con openssl:

SECRETO='pega-aqui-el-secreto'
CUERPO='{"event":"deploy-finished","title":"Despliegue 42 terminado","id":"42"}'
FIRMA=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO" | sed 's/^.* //')

curl -i -X POST "https://<tu-usuario>-cloud.elyra.sh/hooks/<id-de-la-automatización>" \
  -H "Content-Type: application/json" \
  -H "X-Elyra-Event: deploy-finished" \
  -H "X-Elyra-Signature-256: sha256=$FIRMA" \
  --data-binary "$CUERPO"

Respuesta de éxito: 202, sin cuerpo. La automatización se ejecuta después.

Cosas que suelen salir mal:

Firma los bytes exactos que envías. Si cambias un espacio o un salto de línea después de firmar, la firma deja de coincidir. Por eso --data-binary y no -d.
Las llamadas repetidas con el mismo cuerpo suelen ignorarse. El webhook genérico no tiene un identificador de entrega, así que Elyra usa el contenido del cuerpo: el mismo cuerpo dos veces devuelve 202, pero dispara una sola vez. Esa memoria dura hasta 24 horas y no es una garantía: vuelve a empezar cuando Elyra se reinicia y guarda un número limitado de cuerpos. Incluye un campo que cambie en cada llamada, como un id o una hora, y no cuentes con Elyra para bloquear repeticiones.
Qué ve la automatización. Elyra guarda solo un resumen de lo que llegó y nunca el cuerpo entero: evento, repositorio, título, dirección, autor y número, cuando el cuerpo trae title, url, number, entre otros. Ese resumen llega a las acciones como dato externo no confiable: se le avisa al agente que no siga instrucciones contenidas en él.

Configurarlo en GitHub

En el repositorio, Settings > Webhooks > Add webhook:

Payload URL: la URL copiada del detalle de la automatización.
Content type: application/json. Otro formato no se lee.
Secret: el secreto de la automatización.
Which events…: elige Let me select individual events y marca los que usa la automatización: Pull requests (PR abierto, PR fusionado, revisión solicitada), Workflow runs, Check suites o Check runs (CI falló) e Issues (issue abierta).
Add webhook.

Elyra comprueba la firma de GitHub (X-Hub-Signature-256) y usa la cabecera de entrega (X-GitHub-Delivery) para no disparar dos veces la misma entrega.

Evento de la automatización	Qué envía GitHub
PR abierto	`pull_request` con acción `opened`
PR fusionado	`pull_request` con acción `closed` y el PR fusionado
Revisión solicitada	`pull_request` con acción `review_requested`
CI falló	`workflow_run`, `check_suite` o `check_run` con conclusión `failure`
Issue abierta	`issues` con acción `opened`

Configurarlo en GitLab

En el proyecto, Settings > Webhooks > Add new webhook:

URL: la URL copiada del detalle de la automatización.
Secret token: el secreto de la automatización. GitLab lo envía en la cabecera X-Gitlab-Token.
Trigger: marca Merge request events (PR abierto y fusionado), Pipeline events (CI falló) e Issues events (issue abierta).
Add webhook.

GitLab no tiene un evento equivalente a “revisión solicitada”, así que ese evento no se dispara allí.

Qué responde Elyra

Para no revelar si una automatización existe, casi todo rechazo devuelve 404, sin cuerpo.

Respuesta	Cuándo
`202`	Aceptado; o entrega repetida; o evento del proveedor que Elyra no reconoce (como el `ping` de GitHub)
`404`	URL que no existe o mal formada; automatización desactivada, eliminada o con el secreto revocado; firma que no coincide; cuerpo que no es un objeto JSON; GitHub o GitLab con un evento que la automatización no marcó o de otro repositorio
`405`	El método no fue `POST`
`408`	El cuerpo no terminó de llegar en 10 segundos
`413`	El cuerpo pasa de 1 MiB
`503`	El servicio de automatizaciones todavía no está disponible

Si la automatización está activa y la firma no coincide, Elyra registra una ejecución “No ejecutada” con el motivo “entrega recusada: assinatura inválida” (se muestra en portugués), como máximo una cada 30 segundos. Es la señal de que alguien está llamando con el secreto equivocado, o con uno antiguo.

Rotar y revocar el secreto

Quiero…	Pantalla	CLI
Generar otro secreto (e invalidar el anterior)	Detalle de la automatización: Rotar secreto	`elyra automations webhook-secret rotate <id>`
Invalidar el secreto ahora, sin generar otro	Detalle de la automatización: Revocar secreto	`elyra automations webhook-secret revoke <id>`

Rotar imprime la nueva URL y el nuevo secreto, una vez. El secreto anterior deja de valer al instante: actualiza el sistema de origen enseguida.
Revocar hace que toda llamada nueva sea rechazada al instante. El historial y las acciones se mantienen. Para volver a recibir llamadas, rota el secreto.
La CLI responde “Webhook secret revoked.” o, cuando no había un secreto activo, “Webhook secret was not found or was already revoked.”
El <id> es el de la propia automatización (elyra automations list).

¿Y el Cloud sin ventana?

Elyra Cloud es la app funcionando en un servidor, sin ventana. Una llamada de webhook que llega a él ejecuta la cadena de acciones igual, sin nadie frente a la pantalla. Dos acciones no tienen dónde aparecer sin ventana y fallan con un aviso claro: Notificación y Abrir conversación. Para estos disparadores, prefiere acciones como Comando en el terminal y Agente en un workspace.

Alcance y límites

El secreto es la llave de la puerta. Quien lo tiene dispara la automatización. Guárdalo como una contraseña, nunca en un repositorio público, y rótalo si se filtra.
Un disparo cada 30 segundos, por automatización. Las llamadas más cercanas se vuelven “No ejecutada: límite de disparos”.
Sin cola. Cloud apagado en el momento de la llamada: quien llamó tiene que reenviar.
El cuerpo de la llamada nunca se guarda. Solo el resumen descrito arriba.