主な機能
- 最新の認証メカニズムを備えた、HTTP POST およびPUT データ取り込み用のパブリックAPI エンドポイントの公開
- CORS サポートを備えた、ユーザーベースのレート制限と同時リクエスト管理
- セキュリティを強化するHMAC 署名認証と、カスタムレスポンスイベントのスクリプト
- XML Map コネクタとの統合およびワークフロー自動化のためのサンプルリクエストテンプレート
概要
Webhook コネクタにより、HTTP POST およびPUT を介して フローにデータを入力できます。各Webhook コネクタは、外部クライアントがXML およびJSON ペイロードを送信できるエンドポイントをアプリケーション内に公開します。これらのペイロードはアウトプットファイルに書き込まれ、フロー内の次のコネクタに渡されます。 Webhook コネクタでサンプルリクエストを指定すると、エンドポイントにPOST されたデータの変換プロセスを簡素化できます。XML サンプルを指定し、Webhook コネクタがフロー内でXML Map コネクタに接続されている場合、XML Map コネクタは、エンドポイントにPOST されるXML ファイルの想定される構造を自動的に検出します。その後、XML Map コネクタのノード値エディタを使用して、この構造をターゲットのXML 構造にマッピングできます。コネクタの設定
このセクションには、設定可能なすべてのコネクタプロパティが記載されています。Settings タブ
Connector Details
コネクタのコア操作に関連する設定。Advanced Settings
Request Details タブ
受信データの想定される構造を表すXML またはJSON テンプレートを指定します。サンプルリクエストを指定する主なメリットは、Webhook コネクタをフロー内のXML Map コネクタに接続する場合に得られます。API データをEDI ドキュメントやデータベースへの挿入など、他の形式に変換する必要がある場合は、XML Map コネクタを使用してください。 XML Map コネクタはサンプルリクエストのXML 構造を検出し、これをXML Map コネクタのSource File として使用します。ターゲット形式を表すXML 構造をDestination File としてアップロードし、ノード値エディタを使用してソース構造を送信先に変換します。Users タブ
Users タブでは、次のことができます：- 関連するauthtoken およびOAuth 2.0 認証情報を持つユーザーの作成
- POST および/またはPUT 権限の定義
- 各ユーザーが1時間あたりに実行できるリクエスト数の指定
- 許可される同時リクエスト数の指定
ここでのリクエスト設定は、Server タブのデフォルトレート制限セクションの設定を上書きします。
Server タブ
Trusted IP Addresses
Default Rate Limits (Per User)
Users タブで値が指定されていない場合に、許可されるリクエスト数を制限する設定。Cross-Origin Resource Sharing (CORS)
クロスオリジンリソースを配信するためのCORS の使用を制御する設定。Advanced Settings
Advanced タブ
Logging
Miscellaneous
Alerts タブ
SLAs タブ
HMAC 認証
HMAC（Hash-based Message Authentication Code）署名認証は、Webhook リクエストの真正性と完全性を検証する暗号化方式です。共有シークレットキーを使用して各リクエストに固有の署名を生成し、次を保証します：- リクエストの真正性：リクエストが信頼できるソースから発信されたことを確認します
- データの完全性：リクエストペイロードが送信中に改ざんされていないことを検証します
- リプレイ攻撃の防止：傍受されたリクエストの悪意ある再利用から保護します
設定
- HMAC 認証の有効化
- Webhook コネクタの設定でEnable HMAC Authentication をチェックします。
- 任意で、HMAC Signature Header の値をカスタマイズします（デフォルトは
x-cdata-hmac-signatureです）。
ユーザーへのHMAC キーの設定
HMAC 認証を有効化したあと：- Webhook コネクタのUsers タブに移動します。
- 認証された各Webhook ユーザーのHMAC キーを設定します：
- 各ユーザーに対してHMAC キーが自動的に生成されます。自動生成されたキーをカスタム値で上書きできます。各ユーザーは、Webhook リクエストの有効な署名を生成するために、割り当てられたHMAC キーを使用する必要があります。
認証トークン認証
ユーザーは、リクエストにauthtoken を指定することでWebhook リソースにアクセスできます。Users タブでユーザーを追加または編集し、Authentication タブに移動して、ユーザーとauthtoken を管理します。 ユーザーがWebhook エンドポイントを呼び出す前に、接続用の信頼できるIP アドレスも設定する必要があります。これらはServer タブのTrusted IP Addressesセクションで設定します。デフォルトでは、すべてのIP アドレスが制限されています。ベーシック認証での認証トークンの使用
ベーシック認証を使用する場合は、ユーザーのauthtoken をパスワードとして入力します。HTTP ヘッダーでの認証トークンの使用
HTTP リクエストの一部として、authtoken を含むHTTP ヘッダーx-{companyName}-authtoken を追加します。
クエリ文字列パラメータとしての認証トークンの使用
コネクタがクエリ文字列パラメータでauthtoken を渡すことを許可するには、Server タブのAdvanced SettingsセクションでAllow authtoken in URL をチェックします。 この機能を有効化したあと、HTTP フォームポストデータの一部として、またはクエリパラメータとして指定する@authtoken パラメータの値としてauthtoken を指定できます。
OAuth 2.0 認証
ユーザーは、OAuth 2.0 認証を使用してWebhook リソースをセキュアにできます。Users タブでユーザーを追加または編集し、Authentication タブに移動して、ユーザーとOAuth 認証情報を管理します。データの受信
Webhook エンドポイントにデータがアップロードされると、Web リクエストのボディがアウトプットファイルとして書き込まれ、フロー内の次のコネクタに渡されます。これにより、外部API 呼び出しを介して ワークフローを起動する柔軟な方法が提供されます。カスタムレスポンス
通常、Webhook コネクタはリクエストが受け入れられたことを示すトークンレスポンスとともにポストデータを受け入れますが、Response イベントを使用してレスポンスをカスタマイズできます。このイベントでは、_request、_httpheaders、_response、_message の特別なアイテムが利用できます。指定した場合、コネクタは_response アイテムを通じてカスタムレスポンスが提供されることを想定します。
Response イベントを使用して、次の属性でカスタムアウトプットアイテムをプッシュすることもできます：
- Filename：フローに渡すアウトプットメッセージのファイル名。
- Data：フローに渡すメッセージに含めるデータ。バイナリデータの場合は、代わりにBase64Data 属性を使用します。
- Base64Data：フローに渡すメッセージに含めるBase64 エンコードされたデータ。
- HeaderNames#：フローに渡すメッセージに含めるヘッダー名のリスト。一致するインデックスでこれらのヘッダーの値を指定するには、HeaderValues 属性を使用します。
- HeaderValues#：フローに渡すメッセージに含めるヘッダー値のリスト。これらの値は、HeaderNames リスト内の一致するインデックスで定義されたヘッダー名に使用されます。
- Logs#：トランザクションのログに含めるログエントリのリスト。
レスポンスの例
カスタムのファイル名とヘッダーを付けて、Webhook リクエストのボディを含むファイルをフローに渡すには、Response イベント内のScript は次のようになります：
Response イベント内のScript は次のようになります：
Response イベントに設定すると、クライアントは次のようなリクエストを送信できます：