ドキュメントAPIオープンプラットフォームWebhook エンドポイント

Webhook エンドポイント

ワークフロートリガー + 承認応答 (POST + GET ワンクリックリンク)。

Webhook エンドポイントは、「外部システムからのアクティブなプッシュイベント」に使用されます。 2 つのカテゴリ: ワークフロートリガー (外部システムがデータをプッシュ → ワークフローの実行をプルアップ) と承認コールバック (外部システムが決定をプッシュ → Manual_approval ステップを完了)。

1. ワークフローのトリガー

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

まずコンソールで Webhook を作成します。対象のワークフローにバインドし、WEBHOOK_TRIGGER スコープを持つ API Key を選択します。その後、外部システムはトリガー URL に JSON オブジェクト（上限 1 MB）を POST します。payload のトップレベルフィールドは variableMapping または同名ルールに従ってワークフロー変数にマッピングされます。

作成手順の全体、トリガーの curl の例、変数マッピングルール、エラーコード表、HMAC 互換モードについては、以下を参照してください Webhook によるワークフローのトリガー。本ページではオープンプラットフォーム側のエンドポイント契約のみを記載します。

権限の境界

ダブルチェック

Webhook は作成時に 1 つの apiKeyId がバインドされます。トリガー時、リクエスト Token から解析される Key は、バインドされたものと完全に一致する必要があり（key id が完全に等しい）、かつ Key と Webhook は同じアカウントに属している必要があります。これにより、WEBHOOK_TRIGGER スコープを持つ Key が 1 つ漏洩したとしても、明示的にバインドされた Webhook のみをトリガーでき、他人のワークフローはトリガーできないことが保証されます。API Key がバインドされた Webhook は HMAC 署名を受け付けなくなります。

2.承認応答（POSTメソッド）

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

外部システム（自動化ロジック、Slack Bot、メール返信処理など）で承認の判断を送信するために使用します。リクエストボディの上限は 64 KB です。

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

成功した応答:

json

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

リクエストフィールド

フィールド	タイプ	説明
`approvalId`	string	Manual_approvalステップイベント/承認リスト/通知テンプレートから取得
`decision`	string	「承認」または「拒否」（大文字と小文字は区別されません）
`comment`	string	オプション、承認履歴に記録されます

エラーレスポンス

ステータスコード	意味
`400`	decision が approve / reject のいずれでもない
`401`	API Key が無効、または APPROVAL_RESPOND スコープが不足している
`403`	Key の所有者がその承認の承認権限を持つ承認者ではない
`404`	承認が存在しない、または Key の所有者に対して非表示である
`409`	承認はすでに処理済みで、重複して判断することはできません
`429`	リクエストが頻繁すぎます。レスポンスには Retry-After と X-RateLimit-* ヘッダーが付きます

3. 承認ワンクリックリンク（GETメソッド）

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
認証: API Key（query パラメータ）· Scope: APPROVAL_RESPOND

承認者が電子メール/Slack/Telegram 内のリンクをクリックして承認を完了できるようにするために、GET 形式のエンドポイントが提供されます。応答は JSON ではなく HTML ページです。

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

リンクを初めて開いたときは確認ページのみが表示され、ページ上の確認ボタンをクリックする（URL に confirm=1 が追加される）ことで初めて実際に判断が送信されます。メールクライアントや IM のリンクプレビューボットは確認ページのみを取得するため、誤って承認することはありません。

このようなリンクを承認通知メッセージに埋め込むことができます。例:

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>)

ワンクリックリンクのセキュリティ制約

ワンクリック承認用の API Key には短めの有効期限を設定すべきです（24～72 時間を推奨）
範囲は APPROVAL_RESPOND に厳密に制限されており、他の権限と混合しないでください。
リンクの転送は、承認権限を引き渡すことと同じです。グループ内にクリアテキストのリンクを投稿しないでください。プライベートメッセージで送信することをお勧めします。
リンク漏洩の場合: コンソールに入り、キーを直ちに取り消します。承認/拒否された承認は監査ログを通じて追跡できます。

HMAC 署名（旧来の連携との互換用）

API Key がバインドされておらず secretKey のみが設定された Webhook は、引き続き HMAC-SHA256 共有鍵モード（リクエストヘッダー X-Webhook-Signature）を使用します。Webhook に API Key をバインドすると、HMAC は受け付けられなくなり、この移行は一方向です。新規の連携では直接 API Key モードを使用してください。署名アルゴリズムと移行の詳細は以下を参照してください Webhook によるワークフローのトリガー。