Acionamento por Webhook

Um Webhook permite que sistemas externos (GitHub, CI/CD, Lark, IoT, uma API upstream) iniciem uma execução de workflow diretamente via HTTP POST. Abordagem recomendada: vincular o Webhook a uma chave API com o escopo WEBHOOK TRIGGER e autenticar solicitações de gatilho com essa chave.

Criar um Webhook e vincular uma chave API

1. Em Console → Configurações de conta → teclas API, crie uma chave e verifique o escopo WEBHOOK_TRIGGER (verChaves e escopos da API）
2. Crie um Webhook na lista Webhook ou na página de detalhes do workflow, escolha o workflow de destino e ligue esta Chave. O criador precisa de permissão de edição no workflow, e a chave ligada deve ser sua

Você também pode usar a API de gerenciamento (com uma sessão de console logado):

curl -X POST https://braidrun.com/api/webhooks \
  -H "Authorization: Bearer <console-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "GitHub Push Webhook",
    "apiKeyId": "<api-key-id>",
    "variableMapping": {
      "branch": "ref",
      "repo_name": "repo"
    }
  }'

A resposta inclui um webhook-id único. O URL do gatilho é:

POST https://braidrun.com/api/webhooks/<webhook-id>/trigger

Webhook conta escalas com seu plano: 3 no Pro, 10 na Equipe.

Acionar workflow

curl -X POST https://braidrun.com/api/webhooks/<webhook-id>/trigger \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repo": "my-app"
  }'

As credenciais podem ser passadas de três maneiras, que o servidor verifica nesta ordem:

Authorization: Bearer dyk_<id>_<secret>      # 推荐
X-API-Key: dyk_<id>_<secret>                  # 无法自定义 Authorization 头时
POST .../trigger?api_key=dyk_<id>_<secret>    # 仅限无法设置 header 的场景

Retornos de gatilho bem-sucedidos:

{
  "executionId": "exec_a3b9c8...",
  "webhookId": "<webhook-id>",
  "workflowId": "<workflow-id>",
  "status": "PENDING",
  "startedAt": 1735632891234
}

Mapeamento variável

Sem variávelMapping, string de nível superior, número e campos booleanos no mapa de carga útil para variáveis de workflow do mesmo nome automaticamente; objetos aninhados e arrays são excluídos do mapeamento automático.

Para renomear, configure variableMapping : a chave é o nome da variável de workflow, o valor é o nome do campo de carga de alto nível. Apenas os campos de nível superior são suportados; as buscas no caminho aninhado não são.

# Webhook 配置
"variableMapping": { "branch": "ref", "repo_name": "repo" }

# 触发 payload
{ "ref": "refs/heads/main", "repo": "my-app" }

# 工作流实际拿到的输入
{ "branch": "refs/heads/main", "repo_name": "my-app" }

Se um campo mapeado estiver faltando na carga útil, a variável não é injetada e o valor padrão no modelo de workflow ainda se aplica (não será sobrescrito com uma string vazia).

Assinaturas HMAC (para integrações legadas)

Um Webhook sem chave de API mas com secretKey set usa o modo HMAC legado: a solicitação de gatilho deve incluir uma assinatura no cabeçalho:

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(rawRequestBody, secretKey))>

Assinatura = HmacSHA256(rawRequestBody, secretKey) , saída como uma cadeia hex, com ou sem o prefixo sha256=. Uma incompatibilidade devolve 401.

Um Webhook com uma chave de API não aceita mais assinaturas HMAC (mesmo que o campo secretKey ainda tenha um valor); migrar para a chave de API é one-way. Um Webhook com nenhum método de autenticação configurado não verifica a identidade no gatilho – o URL em si atua como a credencial, que recomendamos apenas durante a depuração.

O caminho do gatilho legado POST /api/webhook-trigger/{webhookId} ainda está disponível com comportamento idêntico; use o caminho canônico acima para novas integrações.

Respostas de erro

Cenários de acesso comuns

• GitHub push — Mapear o nome do ramo e enviar o autor para variáveis; o workflow constrói, testa e implementa automaticamente
• CI 系统 — Compilação concluída → Webhook aciona pipeline de lançamento subsequente
• Lark / 飞书机器人 — Acione o processamento operacional em lote após receber um comando específico
• IoT 上报 — Alarme do dispositivo → Webhook aciona workflow de solução de problemas e converge alarmes

Objetivos de gestão

Lista GET /api/webhooks, atualização PUT /api/webhooks/{id}, apagar DELETE /api/webhooks/{id}, mais GET /api/webhooks/{id}/stats retorna estatísticas de gatilho; todas estas são endpoints de console autenticados.

Quando o serviço for reiniciado

Uma execução desencadeada pelo Webhook interrompida por uma reinicialização de serviço não irá retomar automaticamente: a carga útil é manuseada quase uma vez, e a plataforma não a reproduz. As execuções já pausadas no manual aprovation são a exceção – elas continuam como de costume uma vez aprovadas. Para repetir, faça com que o sistema upstream envie novamente o pedido de gatilho (isso cria uma nova execução).

Páginas relacionadas

• Endpoint Webhook da plataforma aberta (convocação de aprovação)
• Chaves e escopos da API