Disparador Webhook

Los Webhooks permiten que sistemas externos (GitHub, CI/CD, Lark, IoT, APIs upstream) lancen directamente la ejecución de un workflow mediante un HTTP POST. Práctica recomendada: enlace al Webhook una API Key con el scope de permiso WEBHOOK_TRIGGER, y que la solicitud de disparo se autentique con esta Key.

Crear un Webhook y enlazar una API Key

1. En Consola → Configuración de la cuenta → API keys, cree una Key nueva y marque el scope WEBHOOK_TRIGGER (ver detalles enAPI Key y scopes de permiso）
2. En la lista de Webhooks o en la página de detalle del workflow, cree un Webhook, elija el workflow de destino y enlace esta Key. El creador necesita permiso de edición sobre el workflow, y la Key enlazada debe estar a su nombre

También puede usar la API de gestión (con sesión iniciada en la consola):

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"
    }
  }'

La respuesta incluye un webhook-id único, y la URL de activación es:

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

La cantidad de Webhooks depende del plan: Pro 3, Team 10.

Desencadenar el flujo de trabajo

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"
  }'

Las credenciales pueden enviarse de tres formas, que el servidor reconoce en el siguiente orden:

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

Devoluciones exitosas del disparador:

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

Mapeo de variables

Sin configurar variableMapping, los campos de tipo string, número o booleano del nivel superior del payload se asignan automáticamente a variables del workflow con el mismo nombre; los objetos anidados y los arreglos no participan en la asignación automática.

Cuando se necesita renombrar, se configura variableMapping : la clave es el nombre de la variable del workflow y el valor es el nombre del campo de nivel superior del payload. Solo se admiten campos de nivel superior, no la lectura por rutas anidadas.

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

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

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

Cuando en el payload falta un campo asignado, esa variable no se inyecta y el valor predeterminado de la plantilla del workflow sigue vigente (no se sobrescribe con una cadena vacía).

Firma HMAC (compatibilidad con integraciones antiguas)

Los Webhook que no tienen API Key vinculada pero sí tienen configurado secretKey usan el modo HMAC heredado: la solicitud de activación debe incluir la firma en el header:

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

Firma = HmacSHA256(rawRequestBody, secretKey) , produce una cadena hex; el prefijo sha256= es opcional. Si la comparación falla, devuelve 401.

Un Webhook con API Key vinculada ya no acepta firmas HMAC (aunque el campo secretKey aún tenga valor); la migración a API Key es unidireccional. Un Webhook sin ninguno de los dos métodos de autenticación no verifica la identidad al activarse, la propia URL equivale a la credencial, y solo se recomienda usarlo así durante la etapa de depuración.

La ruta de activación heredada POST /api/webhook-trigger/{webhookId} se mantiene con el mismo comportamiento; para nuevas integraciones use la ruta canónica anterior.

Respuestas de error

Escenarios de acceso comunes

• GitHub push — Asigna el nombre de la rama y el autor del commit a variables; el workflow ejecuta build / test / deploy automáticamente
• CI 系统 — Compilación completada → Webhook activa el proceso de lanzamiento posterior
• Lark / 飞书机器人 — Activar el procesamiento por lotes operativo después de recibir un comando específico
• IoT 上报 — Alarma del dispositivo → Webhook activa el flujo de trabajo de solución de problemas y converge las alarmas

Endpoint de administración

lista GET /api/webhooks, actualizar PUT /api/webhooks/{id}, eliminar DELETE /api/webhooks/{id}, y además GET /api/webhooks/{id}/stats devuelve las estadísticas de activación; todas estas son interfaces con sesión iniciada en la consola.

Cuando se reinicia el servicio

Una execution activada por Webhook que se interrumpe por un reinicio del servicio no se reanuda automáticamente: el payload se procesa como at-most-once y la plataforma no hace reintentos de entrega. Las excepciones son las ejecuciones detenidas en manual_approval a la espera de aprobación, que continúan con normalidad una vez aprobadas. Cuando se necesita reejecutar, basta con que el sistema anterior vuelva a enviar la solicitud de activación (se creará una nueva execution).

Páginas relacionadas

• Endpoint Webhook de la plataforma abierta (callback de aprobación)
• API Key y scopes de permiso