Webhook, GitHub e GitLab

Um webhook deixa outro sistema disparar uma automação: o GitHub quando um PR é aberto, o GitLab quando um pipeline falha, o seu script de deploy quando termina. O sistema de origem faz uma chamada HTTP POST a um endereço da automação, assinada com um segredo que só você e o Elyra conhecem.

Há três jeitos de usar, e os três compartilham endereço e segredo:

Gatilho	Para quê	Como a chamada prova quem é
Webhook (genérico)	Seus scripts, seu CI, qualquer sistema	Cabeçalho X-Elyra-Signature-256
GitHub	Eventos de um repositório do GitHub	Cabeçalho X-Hub-Signature-256 (o padrão do GitHub)
GitLab	Eventos de um projeto do GitLab	Cabeçalho X-Gitlab-Token (o padrão do GitLab)

O que precisa estar de pé

• Elyra Cloud ativo neste computador. É o Cloud que recebe a chamada vinda da internet. Sem ele, os gatilhos GitHub ou GitLab e Webhook aparecem como Requer Elyra Cloud ativo e não podem ser escolhidos; pela CLI, o comando recusa com “GitHub, GitLab, and webhook triggers require an active Elyra Cloud server.”
• O sistema de origem precisa alcançar o endereço do seu Cloud. O endereço é público, no formato https://<seu-usuario>-cloud.elyra.sh/hooks/<id-da-automação>.
• O cofre do sistema disponível. O segredo é guardado cifrado pelo chaveiro do sistema operacional. Se ele não estiver disponível, o Elyra recusa criar o segredo e diz o motivo, em vez de guardá-lo sem proteção.

Se o Cloud estiver desligado quando a chamada chegar, o Elyra não guarda fila: o GitHub, o GitLab ou o seu sistema precisa reenviar.

Cadastrar pela tela, passo a passo

1. Abra Automações > Criar automação.
2. Dê um nome, por exemplo “Avisar quando um deploy terminar”.
3. Em quando isto acontecer, escolha Webhook (ou GitHub ou GitLab, para os provedores).
   • Para GitHub ou GitLab: escolha o provedor, informe o repositório como dono/nome (por exemplo empresa/projeto) e marque os eventos.
4. Escolha no (projeto), no (workspace) e a cadeia de ações em faça isto. Veja Ações.
5. Criar automação.
6. Abra o detalhe da automação. Ali estão:
   • Copiar endereço: a URL que o sistema de origem vai chamar;
   • Copiar segredo: o segredo, mostrado uma única vez;
   • Trocar segredo e Revogar segredo.
7. Copie o segredo na hora e guarde-o no sistema de origem. Ele não volta a ser exibido depois que você sair da tela. Se perdeu, use Trocar segredo para gerar outro.
8. Cole o endereço e o segredo no sistema de origem (veja as seções abaixo) e dispare um teste.

Quando o evento chegar, a execução aparece no Histórico da automação, com “disparada porque…”.

Cadastrar pela CLI

A CLI cria a automação, gera o segredo e imprime o endereço e o segredo uma vez.

Os exemplos usam aspas simples, do bash, do zsh e do Git Bash. No PowerShell e no cmd, as aspas internas do JSON precisam de escape; se o comando disser que o JSON é inválido, é isso.

Webhook genérico

elyra automations create \
  --name "Avisar quando um deploy terminar" \
  --trigger daily --prompt "Deploy terminou" --provider codex \
  --repo meu-projeto \
  --trigger-json '{"kind":"webhook"}' \
  --actions '[{"kind":"notify","title":"Deploy terminou","body":"O sistema de deploy avisou que terminou"}]'

A saída traz, além do resumo da automação:

Webhook URL: https://<seu-usuario>-cloud.elyra.sh/hooks/<id-da-automação>
Webhook secret (copy now): <segredo mostrado só desta vez>

--trigger, --prompt e --provider continuam obrigatórios mesmo com --trigger-json: nos gatilhos que não são horário, eles são o texto que versões antigas do Elyra leem. A cadeia que vale é a de --actions.

GitHub

elyra automations create \
  --name "Revisar PR novo" \
  --trigger daily --prompt "Revisar PR" --provider codex \
  --repo meu-projeto \
  --trigger-json '{"kind":"git-remote","provider":"github","repo":"empresa/projeto","events":["pr-opened"]}' \
  --actions '[{"kind":"run-agent-in-workspace","prompt":"Revise o PR que acabou de abrir","agentId":"codex","workspaceMode":"new_per_run"}]'

GitLab

elyra automations create \
  --name "Investigar pipeline" \
  --trigger daily --prompt "Investigar pipeline" --provider codex \
  --repo meu-projeto \
  --trigger-json '{"kind":"git-remote","provider":"gitlab","repo":"grupo/projeto","events":["ci-failed"]}' \
  --actions '[{"kind":"notify","title":"Pipeline falhou","body":"Veja o GitLab"}]'

Os events aceitos em git-remote são pr-opened, pr-merged, review-requested, ci-failed e issue-opened. O repo precisa ter a forma dono/nome. Os campos de cada ação estão em Ações.

Chamar o webhook genérico

O endereço aceita somente POST, com corpo JSON (um objeto) de até 1 MiB.

Cabeçalho	Valor	Obrigatório
X-Elyra-Signature-256	sha256= seguido do HMAC-SHA256, em hexadecimal, do corpo exato, usando o segredo como chave	Sim
X-Elyra-Event	Nome do evento, só para o histórico. Sem ele, vale o campo event do corpo; sem os dois, webhook	Não
Content-Type	application/json	Recomendado

Exemplo com curl, assinando o corpo com openssl:

SEGREDO='cole-aqui-o-segredo'
CORPO='{"event":"deploy-finished","title":"Deploy 42 concluído","id":"42"}'
ASSINATURA=$(printf '%s' "$CORPO" | openssl dgst -sha256 -hmac "$SEGREDO" | sed 's/^.* //')

curl -i -X POST "https://<seu-usuario>-cloud.elyra.sh/hooks/<id-da-automação>" \
  -H "Content-Type: application/json" \
  -H "X-Elyra-Event: deploy-finished" \
  -H "X-Elyra-Signature-256: sha256=$ASSINATURA" \
  --data-binary "$CORPO"

Resposta de sucesso: 202, sem corpo. A automação roda depois.

Pontos que costumam dar errado:

• Assine os bytes exatos que você envia. Mudou um espaço ou uma quebra de linha depois de assinar, a assinatura deixa de bater. Por isso --data-binary e não -d.
• Chamadas repetidas com o mesmo corpo costumam ser ignoradas. O webhook genérico não tem um identificador de entrega, então o Elyra usa o conteúdo do corpo: o mesmo corpo duas vezes devolve 202, mas só dispara uma vez. Essa memória é de até 24 horas e não é garantia: ela recomeça quando o Elyra reinicia e guarda um número limitado de corpos. Inclua um campo que muda a cada chamada, como um id ou um horário, e não conte com o Elyra para barrar repetição.
• O que a automação enxerga. O Elyra guarda só um resumo do que chegou e nunca o corpo inteiro: evento, repositório, título, endereço, autor e número, quando o corpo traz title, url, number, entre outros. Esse resumo chega às ações como dado externo não confiável: o agente é avisado de que não deve seguir instruções contidas nele.

Configurar no GitHub

No repositório, Settings > Webhooks > Add webhook:

1. Payload URL: o endereço copiado do detalhe da automação.
2. Content type: application/json. Outro formato não é lido.
3. Secret: o segredo da automação.
4. Which events…: escolha Let me select individual events e marque os que a automação usa: Pull requests (PR aberto, PR mergeado, review pedida), Workflow runs, Check suites ou Check runs (CI falhou) e Issues (issue aberta).
5. Add webhook.

O Elyra confere a assinatura do GitHub (X-Hub-Signature-256) e usa o cabeçalho de entrega (X-GitHub-Delivery) para não disparar duas vezes a mesma entrega.

Evento da automação	O que o GitHub envia
PR aberto	pull_request com ação opened
PR mergeado	pull_request com ação closed e o PR mergeado
Review pedida	pull_request com ação review_requested
CI falhou	workflow_run, check_suite ou check_run com conclusão failure
Issue aberta	issues com ação opened

Configurar no GitLab

No projeto, Settings > Webhooks > Add new webhook:

1. URL: o endereço copiado do detalhe da automação.
2. Secret token: o segredo da automação. O GitLab o envia no cabeçalho X-Gitlab-Token.
3. Trigger: marque Merge request events (PR aberto e mergeado), Pipeline events (CI falhou) e Issues events (issue aberta).
4. Add webhook.

O GitLab não tem um evento de “review pedida” equivalente, então esse evento não dispara por lá.

O que o Elyra responde

Para não revelar se uma automação existe, quase toda recusa devolve 404, sem corpo.

Resposta	Quando
202	Aceito; ou entrega repetida; ou evento do provedor que o Elyra não reconhece (como o ping do GitHub)
404	Endereço que não existe ou mal formado; automação desligada, apagada ou com o segredo revogado; assinatura que não bate; corpo que não é um objeto JSON; GitHub ou GitLab com um evento que a automação não marcou ou de outro repositório
405	O método não foi POST
408	O corpo não terminou de chegar em 10 segundos
413	O corpo passa de 1 MiB
503	O serviço de automações ainda não está disponível

Se a automação está ligada e a assinatura não bate, o Elyra registra uma execução “Não executada” com o motivo “entrega recusada: assinatura inválida”, no máximo uma a cada 30 segundos. É o sinal de que alguém está chamando com o segredo errado, ou com um segredo antigo.

Trocar e revogar o segredo

Quero…	Tela	CLI
Gerar outro segredo (e invalidar o anterior)	Detalhe da automação: Trocar segredo	elyra automations webhook-secret rotate <id>
Invalidar o segredo agora, sem gerar outro	Detalhe da automação: Revogar segredo	elyra automations webhook-secret revoke <id>

• Trocar imprime o novo endereço e o novo segredo, uma vez. O segredo anterior para de valer na hora: atualize o sistema de origem logo.
• Revogar faz toda chamada nova ser recusada imediatamente. O histórico e as ações continuam. Para voltar a receber chamadas, troque o segredo.
• A CLI responde “Webhook secret revoked.” ou, quando não havia segredo ativo, “Webhook secret was not found or was already revoked.”
• O <id> é o da própria automação (elyra automations list).

E o Cloud sem janela?

O Elyra Cloud é o app rodando num servidor, sem janela. Uma chamada de webhook que chega a ele executa a cadeia de ações do mesmo jeito, sem ninguém na frente da tela. Duas ações não têm onde aparecer sem janela e falham com um aviso claro: Notificação e Abrir conversa. Para esses gatilhos, prefira ações como Comando no terminal e Agente num workspace.

Escopo e limites

• O segredo é a chave da porta. Quem o tem dispara a automação. Guarde-o como senha, nunca em repositório público, e troque-o se ele vazar.
• Um disparo a cada 30 segundos, por automação. Chamadas mais próximas viram “Não executada: limite de disparos”.
• Sem fila. Cloud desligado na hora da chamada: quem chamou precisa reenviar.
• O corpo da chamada nunca é guardado. Só o resumo descrito acima.

Ver também

• Gatilhos
• Ações
• Execuções e histórico