DokumentOffene API-PlattformWebhook-endpunkt

Webhook-endpunkt

Workflow-Trigger + Genehmigungsantwort (Ein-Klick-Link POST + GET).

Der Webhook-Endpunkt wird für „aktive Push-Ereignisse von externen Systemen“ verwendet. Zwei Kategorien: Workflow-Trigger (externes System überträgt Daten → ruft die Workflow-Ausführung auf) und Genehmigungsrückruf (externes System überträgt Entscheidung → schließt den manuellen_Genehmigungsschritt ab).

1. Workflow-Auslösung

POST /api/webhooks/{webhookId}/trigger
Authentifizierung: API Key (Bearer / X-API-Key / ?api_key) · Scope: WEBHOOK_TRIGGER

Erstellen Sie zunächst in der Konsole einen Webhook: an den Ziel-Workflow gebunden und mit einem API Key, der den WEBHOOK_TRIGGER-Scope besitzt. Anschließend sendet ein externes System per POST ein JSON-Objekt (maximal 1 MB) an die Trigger-URL; die Top-Level-Felder des payload werden gemäß variableMapping oder Namensgleichheitsregel auf Workflow-Variablen abgebildet.

Vollständige Erstellungsschritte, ein curl-Beispiel zum Auslösen, die Regeln der Variablenzuordnung, die Fehlercode-Tabelle und den HMAC-Kompatibilitätsmodus finden Sie unter Workflow per Webhook auslösen; diese Seite listet nur den Endpunkt-Vertrag auf der Seite der offenen Plattform auf.

Berechtigungsgrenzen

Überprüfen Sie es noch einmal

Bei der Erstellung wird dem Webhook eine apiKeyId zugeordnet. Beim Auslösen muss der aus dem Request-Token aufgelöste Key genau der gebundene sein (key id exakt gleich), und Key und Webhook müssen zum selben Konto gehören. Das garantiert: Selbst wenn ein Key mit WEBHOOK_TRIGGER-Scope kompromittiert wird, kann er nur den Webhook auslösen, an den er explizit gebunden ist, und keine Workflows anderer. Ein Webhook mit gebundenem API Key akzeptiert keine HMAC-Signatur mehr.

2. Genehmigungsantwort (POST-Methode)

POST /api/webhook-trigger/approval
Authentifizierung: API Key (Bearer) · Scope: APPROVAL_RESPOND

Dient dazu, in externen Systemen (Automatisierungslogik, Slack Bot, Verarbeitung von E-Mail-Antworten usw.) Genehmigungsentscheidungen einzureichen. Der Request-Body ist auf 64 KB begrenzt.

bash

curl -X POST https://braidrun.com/api/webhook-trigger/approval \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "approvalId": "<approval-id>",
    "decision": "approve",
    "comment": "Approved by CFO via Slack"
  }'

Erfolgreiche Antwort:

json

{
  "ok": true,
  "approvalId": "<approval-id>",
  "decision": "approve"
}

Anforderungsfelder

Feld	Typ	Beschreibung
`approvalId`	string	Rufen Sie Ereignis/Genehmigungsliste/Benachrichtigungsvorlage für den Schritt „manual_approval“ ab
`decision`	string	„genehmigen“ oder „ablehnen“ (Groß- und Kleinschreibung wird nicht beachtet)
`comment`	string	Optional, im Genehmigungsverlauf erfasst

Fehlerantworten

Statuscode	Bedeutung
`400`	decision ist nicht approve / reject
`401`	API Key ist ungültig oder es fehlt der APPROVAL_RESPOND-Scope
`403`	Der Key-Inhaber ist nicht der autorisierte Genehmiger dieser Genehmigung
`404`	Die Genehmigung existiert nicht oder ist für den Key-Inhaber nicht sichtbar
`409`	Die Genehmigung wurde bereits bearbeitet; eine erneute Entscheidung ist nicht möglich
`429`	Zu viele Anfragen; die Antwort enthält die Header Retry-After und X-RateLimit-*

3. Genehmigungs-One-Click-Link (GET-Methode)

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
Authentifizierung: API Key (query-Parameter) · Scope: APPROVAL_RESPOND

Damit der Genehmiger auf einen Link in E-Mail/Slack/Telegram klicken kann, um die Genehmigung abzuschließen, wird ein Endpunkt in Form von GET bereitgestellt. Die Antwort ist eine HTML-Seite, nicht JSON.

text

https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=dyk_<id>_<secret>
https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=dyk_<id>_<secret>&comment=Need%20more%20info

Beim ersten Öffnen zeigt der Link nur eine Bestätigungsseite; erst ein Klick auf die Bestätigungsschaltfläche (die URL wird um confirm=1 ergänzt) reicht die Entscheidung tatsächlich ein. Link-Vorschau-Bots von E-Mail-Clients und IM erfassen nur die Bestätigungsseite und lösen keine versehentliche Genehmigung aus.

Sie können solche Links in Genehmigungsbenachrichtigungen einbetten, zum Beispiel:

markdown

## 工作流等待您批准

请审批 [发票 #1234] 的支付。

[批准](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=<api-key>)
[拒绝](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=<api-key>)

Sicherheitsbeschränkungen für Ein-Klick-Links

Für den API Key der Ein-Klick-Genehmigung sollte eine kurze Gültigkeitsdauer gesetzt werden (empfohlen 24–72 Stunden)
Der Geltungsbereich ist streng auf APPROVAL_RESPOND beschränkt und darf nicht mit anderen Berechtigungen gemischt werden
Das Weiterleiten des Links kommt der Übergabe der Genehmigungsberechtigung gleich – posten Sie keine Klartext-Links in der Gruppe, sondern versenden Sie diese am besten per Privatnachricht
Im Falle eines Verbindungslecks: Betreten Sie die Konsole, um den Schlüssel sofort zu widerrufen. Genehmigte/abgelehnte Genehmigungen können über das Audit-Protokoll nachverfolgt werden.

Hmac-signatur (kompatibel mit älteren Integrationen)

Ein Webhook ohne gebundenen API Key, der nur einen secretKey konfiguriert hat, nutzt weiterhin den HMAC-SHA256-Shared-Secret-Modus (Header X-Webhook-Signature). Sobald einem Webhook ein API Key gebunden wird, wird HMAC nicht mehr akzeptiert; die Migration ist einseitig. Verwenden Sie für neue Integrationen direkt den API-Key-Modus; zum Signaturalgorithmus und zu den Migrationsdetails siehe Workflow per Webhook auslösen.