---
id: "fluxos.automacoes-webhook"
titulo: "Webhook, GitHub e GitLab"
resumo: "Dispare uma automação por uma chamada HTTP assinada: cadastro na tela e pela CLI, endereço, segredo, curl, GitHub, GitLab, respostas e rotação do segredo."
idioma: "pt-br"
tipo: "guia"
categoria: "quadro"
aplicavelDesde: "0.0.16"
capabilities: ["automations.create"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "c9111826ca9805943bfb14a0fa634d5180f3a439"
revisaoFonte: "2026-10-11"
revisor: "mantenedor (2026-10-11)"
rota: "/docs/pt-br/fluxos/automacoes-webhook/"
fonte: "pt-br/fluxos/automacoes-webhook.md"
caminhoPublico: "docs/publica/pt-br/fluxos/automacoes-webhook.md"
hashFonte: "sha256:2b509d370ae030916e4236a4ad2ce8aa6870b5cae6dd61fadcc568b3030c71dc"
hashDestaPagina: "sha256:2b509d370ae030916e4236a4ad2ce8aa6870b5cae6dd61fadcc568b3030c71dc"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
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.

![Gatilhos que dependem do Cloud aparecem como "Requer Elyra Cloud ativo" enquanto o Cloud não está ativo](/docs/capturas/automacoes/gatilhos-escolher.webp)

## 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](/docs/pt-br/fluxos/automacoes-acoes/).
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

```bash
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

```bash
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

```bash
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](/docs/pt-br/fluxos/automacoes-acoes/#pela-linha-de-comando).

## 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`:

```bash
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](/docs/pt-br/fluxos/automacoes-gatilhos/)
- [Ações](/docs/pt-br/fluxos/automacoes-acoes/)
- [Execuções e histórico](/docs/pt-br/fluxos/automacoes-execucoes/)