#ワークフロー Webhook 連携

Webhook トリガーを使うと、NocoBase はサードパーティシステムからの HTTP 呼び出しを受け取り、ワークフローを自動的にトリガーできます。これにより、外部システムとのシームレスな連携が実現します。

#概要

Webhook は「リバース API」メカニズムの一種で、特定のイベントが発生した際に外部システムが NocoBase にデータを能動的に送信できるようにします。アクティブポーリングと比較して、Webhook はよりリアルタイムで効率的な連携方法を提供します。

#典型的な利用シーン

#フォームデータの送信

外部のアンケートシステム、登録フォーム、顧客フィードバックフォームなどでユーザーがデータを送信した後、Webhook を介して NocoBase にデータがプッシュされ、自動的にレコードが作成されたり、確認メールの送信やタスクの割り当てといった後続の処理がトリガーされたりします。

#メッセージ通知

WeCom、DingTalk、Slack などのサードパーティメッセージングプラットフォームからのイベント（新着メッセージ、@メンション、承認完了など）は、Webhook を介して NocoBase 内の自動処理プロセスをトリガーできます。

#データ同期

CRM、ERP などの外部システムでデータが変更された際、Webhook を介して NocoBase にリアルタイムで更新がプッシュされ、データ同期が維持されます。

#サードパーティサービス連携

• GitHub: コードプッシュ、PR 作成などのイベントが自動化ワークフローをトリガー
• GitLab: CI/CD パイプラインのステータス通知
• フォーム送信: 外部フォームシステムから NocoBase へのデータ送信
• IoT デバイス: デバイスの状態変化、センサーデータ報告

#機能

#柔軟なトリガーメカニズム

• GET、POST、PUT、DELETE などの HTTP メソッドをサポート
• JSON、フォームデータなどの一般的な形式を自動的に解析
• リクエスト検証を設定可能で、信頼できるソースからのアクセスを保証

#データ処理機能

• 受信したデータはワークフロー内で変数として利用できます
• 複雑なデータ変換および処理ロジックをサポート
• 他のワークフローノードと組み合わせて、複雑なビジネスロジックを実装できます

#セキュリティ

• 署名検証をサポートし、偽造リクエストを防止
• IP ホワイトリストを設定可能
• HTTPS 暗号化通信

#利用手順

#1. プラグインのインストール

プラグインマネージャーで ワークフロー：Webhook トリガー プラグインを見つけてインストールします。

注意: このプラグインは商用プラグインであり、別途購入またはサブスクリプションが必要です。

#2. Webhook ワークフローの作成

1. ワークフロー管理ページに移動します
2. ワークフローを作成をクリックします
3. トリガータイプとしてWebhook トリガーを選択します

4. Webhook パラメータを設定します

• リクエストパス: カスタム Webhook URL パス
• リクエストメソッド: 許可する HTTP メソッド (GET/POST/PUT/DELETE) を選択します
• 同期/非同期: ワークフローの実行完了を待って結果を返すかどうかを選択します
• 検証: 署名検証またはその他のセキュリティメカニズムを設定します

#3. ワークフローノードの設定

ビジネス要件に基づいてワークフローノードを追加します。例えば、以下のようなものがあります。

• コレクション操作: レコードの作成、更新、削除
• 条件ロジック: 受信したデータに基づいて条件分岐
• HTTP リクエスト: 他の API を呼び出す
• 通知: メール、SMS などを送信
• カスタムコード: JavaScript コードを実行

#4. Webhook URL の取得

ワークフロー作成後、システムは一意の Webhook URL を生成します。通常、形式は次のとおりです。

https://your-nocobase-domain.com/api/webhooks/your-workflow-key

#5. サードパーティシステムでの設定

生成された Webhook URL をサードパーティシステムに設定します。

• フォームシステムでデータ送信コールバックアドレスを設定
• GitHub/GitLab で Webhook を設定
• WeCom/DingTalk でイベントプッシュアドレスを設定

#6. Webhook のテスト

Postman や cURL などのツールを使用して Webhook をテストします。

curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"message":"Hello NocoBase"}}'

#リクエストデータへのアクセス

ワークフローでは、変数を通じて Webhook が受信したデータにアクセスできます。

• {{$context.data}}: リクエストボディデータ
• {{$context.headers}}: リクエストヘッダー情報
• {{$context.query}}: URL クエリパラメータ
• {{$context.params}}: パスパラメータ

#レスポンス設定

#同期モード

ワークフローの実行完了後に結果を返します。以下を設定できます。

• レスポンスステータスコード: 200、201 など
• レスポンスデータ: カスタム JSON レスポンス
• レスポンスヘッダー: カスタム HTTP ヘッダー

#非同期モード

すぐに確認応答を返し、ワークフローはバックグラウンドで実行されます。以下のような場合に適しています。

• 時間のかかるワークフロー
• 実行結果を返す必要がないシナリオ
• 高並行処理シナリオ

#セキュリティのベストプラクティス

#1. 署名検証の有効化

ほとんどのサードパーティサービスは署名メカニズムをサポートしています。

// 示例: 验证 GitHub Webhook 签名
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

#2. HTTPS の使用

NocoBase が HTTPS 環境にデプロイされていることを確認し、データ転送のセキュリティを保護します。

#3. リクエストソースの制限

IP ホワイトリストを設定し、信頼できるソースからのリクエストのみを許可します。

#4. データ検証

ワークフローにデータ検証ロジックを追加し、受信したデータの形式が正しく、内容が有効であることを確認します。

#5. 監査ログ

すべての Webhook リクエストを記録し、追跡や問題のトラブルシューティングに役立てます。

#よくある質問

#Webhook がトリガーされない場合

1. Webhook URL が正しいか確認してください
2. ワークフローのステータスが「有効」になっているか確認してください
3. サードパーティシステムの送信ログを確認してください
4. ファイアウォールとネットワーク設定を確認してください

#Webhook のデバッグ方法

1. ワークフローの実行記録で、リクエストと呼び出し結果の詳細情報を確認します
2. Webhook テストツール (Webhook.site など) を使用してリクエストを検証します
3. 実行記録で主要なデータとエラーメッセージを確認します

#リトライの処理方法

一部のサードパーティサービスは、成功応答を受信しなかった場合に再送信を試みます。

• ワークフローが冪等性を持つことを確認します
• 一意の識別子を使用して重複排除を行います
• 処理済みのリクエスト ID を記録します

#パフォーマンス最適化のヒント

• 時間のかかる操作には非同期モードを使用します
• 条件ロジックを追加して、処理不要なリクエストをフィルタリングします
• 高並行処理シナリオでは、メッセージキューの使用を検討します

#シナリオ例

#外部フォーム送信の処理

// 1. データソースの検証
// 2. フォームデータの解析
const formData = context.data;

// 3. 顧客レコードの作成
// 4. 担当者への割り当て
// 5. 送信者への確認メール送信
if (formData.email) {
  // メール通知を送信
}

#GitHub コードプッシュ通知

// 1. プッシュデータの解析
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

// 2. メインブランチの場合
if (branch === 'main') {
  // 3. デプロイプロセスをトリガー
  // 4. チームメンバーに通知
}

#関連リソース

• ワークフロープラグインのドキュメント
• ワークフロー：Webhook トリガー
• ワークフロー：HTTP リクエストノード
• API キー認証