Déclencheur Webhook

Un Webhook permet à un système externe (GitHub, CI/CD, Lark, IoT, API en amont) de lancer directement l'exécution d'un workflow via une requête HTTP POST. Pratique recommandée : lier au Webhook une API Key dotée du scope de permission WEBHOOK_TRIGGER, et authentifier la requête de déclenchement avec cette Key.

Créer un Webhook et y lier une API Key

1. Dans Console → Paramètres du compte → Clés API, créez une nouvelle Key et cochez le scope WEBHOOK_TRIGGER (voirAPI Key et scopes de permission）
2. Créez un Webhook depuis la liste des Webhook ou la page de détails du workflow, sélectionnez le workflow cible et liez-y cette Key. Le créateur doit disposer d'un droit de modification sur le workflow, et la Key liée doit lui appartenir

Vous pouvez aussi passer par l'API de gestion (en session console connectée) :

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 réponse contient un webhook-id unique ; l'URL de déclenchement est :

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

Le nombre de Webhooks dépend de la formule : 3 pour Pro, 10 pour Team.

Déclencher le flux de travail

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

Les identifiants peuvent être transmis de trois manières ; le serveur les reconnaît dans l'ordre suivant :

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

Retours déclencheurs réussis :

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

Mappage de variables

Sans configuration de variableMapping, les champs de type chaîne, nombre ou booléen situés au premier niveau du payload sont automatiquement mappés vers des variables de workflow de même nom ; les objets imbriqués et les tableaux ne participent pas au mappage automatique.

Pour renommer, configurez variableMapping : la clé est le nom de la variable de workflow, la valeur est le nom du champ de premier niveau du payload. Seuls les champs de premier niveau sont pris en charge, pas les chemins imbriqués.

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

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

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

Si un champ mappé est absent du payload, la variable n'est pas injectée et la valeur par défaut du modèle de workflow reste effective (elle n'est pas écrasée par une chaîne vide).

Signature HMAC (compatibilité avec les anciennes intégrations)

Les Webhooks sans API Key associée mais avec un secretKey configuré fonctionnent en mode HMAC hérité : la requête de déclenchement doit inclure une signature dans le header :

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

signature = HmacSHA256(rawRequestBody, secretKey) , produisant une chaîne hex ; le préfixe sha256= est facultatif. Une comparaison qui échoue renvoie une erreur 401.

Un Webhook associé à une API Key n'accepte plus les signatures HMAC (même si le champ secretKey a encore une valeur) ; la migration vers l'API Key est unidirectionnelle. Un Webhook sans aucune des deux authentifications configurées ne vérifie pas l'identité lors du déclenchement : l'URL elle-même fait office d'identifiant, ce qui n'est recommandé qu'en phase de débogage.

L'ancien chemin de déclenchement POST /api/webhook-trigger/{webhookId} est conservé et se comporte de façon identique ; pour les nouvelles intégrations, utilisez le chemin canonique ci-dessus.

Réponses d'erreur

Scénarios d'accès courants

• GitHub push — Mappez le nom de branche et l'auteur du commit vers des variables ; le workflow effectue automatiquement build / test / deploy
• CI 系统 — Construction terminée → Webhook déclenche le pipeline de versions ultérieures
• Lark / 飞书机器人 — Déclencher un traitement opérationnel par lots après réception d'une commande spécifique
• IoT 上报 — Alarme de l'appareil → Webhook déclenche le flux de travail de dépannage et fait converger les alarmes

Point de terminaison de gestion

liste GET /api/webhooks, mise à jour PUT /api/webhooks/{id}, suppression DELETE /api/webhooks/{id} ; il existe également GET /api/webhooks/{id}/stats qui renvoie les statistiques de déclenchement ; ce sont toutes des interfaces nécessitant une session console authentifiée.

Lorsque le service redémarre

Une execution déclenchée par Webhook et interrompue par un redémarrage du service ne reprend pas automatiquement : le payload est traité en at-most-once, la plateforme ne rejoue rien. Les exécutions arrêtées en attente d'approbation à un manual_approval font exception et se poursuivent normalement une fois l'approbation accordée. Pour relancer, il suffit que le système amont renvoie une requête de déclenchement (une nouvelle execution est alors créée).

Pages connexes

• Point de terminaison Webhook de la plateforme ouverte (rappel d'approbation)
• API Key et scopes de permission