Webhook-trigger

Ein Webhook lässt externe Systeme (GitHub, CI/CD, Lark, IoT, vorgelagerte API) per HTTP POST direkt eine Workflow-Ausführung anstoßen. Empfohlenes Vorgehen: Binden Sie dem Webhook einen API Key mit dem Berechtigungs-Scope WEBHOOK_TRIGGER, und authentifizieren Sie die Trigger-Anfrage mit diesem Key.

Einen Webhook erstellen und einen API Key binden

1. Legen Sie unter Konsole → Kontoeinstellungen → API-Schlüssel einen neuen Key an und wählen Sie beim scope WEBHOOK_TRIGGER (Details sieheAPI Key und Berechtigungs-Scopes）
2. Legen Sie in der Webhook-Liste oder auf der Workflow-Detailseite einen neuen Webhook an, wählen Sie den Ziel-Workflow und binden Sie diesen Key. Der Ersteller benötigt Bearbeitungsrechte für den Workflow, und der gebundene Key muss auf ihn selbst lauten

Alternativ über die Management-API (im angemeldeten Zustand der Konsole):

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

Die Antwort enthält eine eindeutige webhook-id, die Trigger-URL lautet:

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

Die Anzahl der Webhooks richtet sich nach dem Tarif: Pro 3, Team 10.

Workflow auslösen

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

Anmeldedaten können auf drei Arten mitgesendet werden; der Server erkennt sie in folgender Reihenfolge:

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

Erfolgreicher Trigger gibt Folgendes zurück:

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

Variablenzuordnung

Ohne konfiguriertes variableMapping werden String-, Zahlen- und Boolean-Felder auf oberster Ebene des Payloads namensgleich automatisch auf Workflow-Variablen abgebildet; verschachtelte Objekte und Arrays nehmen an der automatischen Zuordnung nicht teil.

Zum Umbenennen konfigurieren Sie variableMapping : Der Schlüssel ist der Name der Workflow-Variable, der Wert ist der Feldname auf der obersten Ebene des Payloads. Es werden nur Felder auf oberster Ebene unterstützt, keine verschachtelten Pfade.

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

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

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

Fehlt ein zugeordnetes Feld im Payload, wird die Variable nicht injiziert und der Standardwert aus der Workflow-Vorlage bleibt weiterhin wirksam (er wird nicht durch einen leeren String überschrieben).

Hmac-signatur (kompatibel mit älteren Integrationen)

Ein Webhook ohne gebundenen API Key, aber mit gesetztem secretKey , nutzt den alten HMAC-Modus: Die Trigger-Anfrage muss im Header eine Signatur mitführen:

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

Signatur = HmacSHA256(rawRequestBody, secretKey) , gibt einen Hex-String aus, das Präfix sha256= ist optional. Schlägt der Abgleich fehl, wird 401 zurückgegeben.

Ein Webhook mit gebundenem API Key akzeptiert keine HMAC-Signaturen mehr (auch wenn das Feld secretKey noch einen Wert hat); die Migration auf API Key ist einseitig. Bei einem Webhook, für den keine der beiden Authentifizierungen konfiguriert ist, wird beim Auslösen keine Identität geprüft; die URL selbst gilt als Anmeldedaten. Dies empfiehlt sich nur in der Debugging-Phase.

Der alte Trigger-Pfad POST /api/webhook-trigger/{webhookId} bleibt erhalten und verhält sich identisch; für neue Integrationen verwenden Sie bitte den oben genannten kanonischen Pfad.

Fehlerantworten

Häufige Zugriffsszenarien

• GitHub push — Branch-Name und Commit-Autor werden auf Variablen abgebildet; der Workflow führt build / test / deploy automatisch aus
• CI 系统 — Build abgeschlossen → Webhook löst nachfolgende Release-Pipeline aus
• Lark / 飞书机器人 — Lösen Sie die operative Stapelverarbeitung aus, nachdem Sie einen bestimmten Befehl erhalten haben
• IoT 上报 — Gerätealarm → Webhook löst den Fehlerbehebungs-Workflow aus und führt Alarme zusammen

Verwaltungs-endpunkte

Liste GET /api/webhooks, Aktualisieren PUT /api/webhooks/{id}, Löschen DELETE /api/webhooks/{id}, außerdem gibt es GET /api/webhooks/{id}/stats , das Trigger-Statistiken zurückgibt; dies sind allesamt Schnittstellen mit Konsolen-Anmeldung.

Wenn der Dienst neu startet

Eine per Webhook ausgelöste Execution wird nach einem Neustart des Dienstes nicht automatisch fortgesetzt: Der Payload wird at-most-once verarbeitet, die Plattform führt kein Replay durch. Eine Ausnahme bildet eine Execution, die bei manual_approval auf eine Freigabe wartet; nach erfolgter Freigabe läuft sie wie gewohnt weiter. Für einen Nachlauf sendet das vorgelagerte System einfach erneut eine Trigger-Anfrage (dabei wird eine neue Execution erstellt).

Verwandte Seiten

• Webhook-Endpunkt der offenen Plattform (Freigabe-Callback)
• API Key und Berechtigungs-Scopes