主な機能
- 最新の認証メカニズムを備えた、HTTP POST およびPUT データ取り込み用のパブリックAPI エンドポイントの公開
- CORS サポートを備えた、ユーザーベースのレート制限と同時リクエスト管理
- セキュリティを強化するHMAC 署名認証と、カスタムレスポンスイベントのスクリプト
- XML Map コネクタとの統合およびワークフロー自動化のためのサンプルリクエストテンプレート
概要
Webhook コネクタにより、HTTP POST およびPUT を介してCData Arc フローにデータを入力できます。各Webhook コネクタは、外部クライアントがXML およびJSON ペイロードを送信できるエンドポイントをアプリケーション内に公開します。これらのペイロードはアウトプットファイルに書き込まれ、フロー内の次のコネクタに渡されます。 Webhook コネクタでサンプルリクエストを指定すると、エンドポイントにPOST されたデータの変換プロセスを簡素化できます。XML サンプルを指定し、Webhook コネクタがフロー内でXML Map コネクタに接続されている場合、XML Map コネクタは、エンドポイントにPOST されるXML ファイルの想定される構造を自動的に検出します。その後、XML Map コネクタのノード値エディタを使用して、この構造をターゲットのXML 構造にマッピングできます。コネクタの設定
このセクションには、設定可能なすべてのコネクタプロパティが記載されています。Settings タブ
Connector Details
コネクタのコア操作に関連する設定。Advanced Settings
Incoming Headers のヘッダー名は大文字と小文字を区別せずに照合されます。昇格されるのはここに記載されたヘッダーのみで、リクエストに含まれていてもこの設定で宣言されていないヘッダーはメッセージヘッダーとして公開されません。宣言されたヘッダーがリクエストに存在しない場合でも、リクエストは引き続き処理され、メッセージヘッダーは空のままになります。
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 の使用を制御する設定。| 設定 | 説明 |
|---|---|
| Enable cross-origin resource sharing (CORS) | CORS を有効にするかどうか。このチェックボックスをオンにした場合にのみ、その他のオプションが利用可能になります。 |
| Allow all domains without '*' | 有効にすると、ドメインオリジンは特定のリストに制限されません。 |
| Access-Control-Allow-Origin | 許可するドメインオリジンのカンマ区切りのリスト。HTTP レスポンスヘッダーとして含まれます。 |
| Access-Control-Allow-Credentials | Cookie などのユーザー認証情報をクロスオリジンリクエストで許可するかどうか。HTTP レスポンスヘッダーとして含まれます。 |
| Access-Control-Allow-Methods | 許可するメソッドのカンマ区切りのリスト。HTTP レスポンスヘッダーとして含まれます。 |
| Access-Control-Allow-Headers | 許可するヘッダーのカンマ区切りのリスト。HTTP レスポンスヘッダーとして含まれます。 |
| Access-Control-Max-Age | Access-Control レスポンスヘッダーの値をキャッシュできる最大時間（秒単位）。 |
Advanced Settings
Advanced タブ
Message
Message 設定は、コネクタがメッセージを検索する方法と、処理後にメッセージを管理する方法を決定します。
Note： 以下の設定は非推奨となり、デフォルトで非表示になっています。以前に有効化またはデフォルト以外の値に設定されていたコネクタにのみ表示されます。処理済みファイルのコピーを保持するには、フロー内のコネクタを右クリックし、成功パスを表示を選択して、成功パスをFile コネクタに接続してください。
| 設定 | 説明 |
|---|---|
| Sent フォルダに保存（非推奨） | コネクタが処理したファイルをSent フォルダにコピーします。デフォルトで無効です。Sent フォルダに保存されたファイルは保存データの暗号化の対象外です。 |
| Sent フォルダのスキーム（非推奨） | 選択した時間間隔でSent フォルダ内のファイルをグループ化します。Sent フォルダに保存が有効な場合のみ適用されます。 |
Logging
ログの作成と保存を制御する設定です。
| 設定 | 説明 |
|---|---|
| Log Level | コネクタが生成するログの詳細度です。サポートを依頼する際は、これをDebug に設定してください。 |
| Log Subfolder Scheme | 選択した間隔に従って、コネクタがLogs フォルダ内のファイルをグループ化するよう指示します。Weekly オプション（デフォルト）は、コネクタが毎週新しいサブフォルダを作成し、その週のすべてのログをそのフォルダに保存するよう指示します。この設定を空白のままにすると、コネクタはすべてのログをLogs フォルダに直接保存します。多数のトランザクションを処理するコネクタでは、サブフォルダを使用することでログを整理しやすくなり、パフォーマンスが向上します。 |
| Log Messages | 処理したファイルのログエントリにファイル自体のコピーを含めるには、これをオンにします。これを無効にすると、Transactions タブからファイルのコピーをダウンロードできなくなる場合があります。 |
Miscellaneous
Miscellaneous 設定は、特定のユースケース向けの設定です。
| 設定 | 説明 |
|---|---|
| Other Settings | 非表示のコネクタ設定をセミコロン区切りのリストで設定できます（例：setting1=value1;setting2=value2）。通常のコネクタのユースケースや機能では、これらの設定の使用は必要ありません。 |
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 呼び出しを介してArc ワークフローを起動する柔軟な方法が提供されます。カスタムレスポンス
通常、Webhook コネクタはリクエストが受け入れられたことを示すトークンレスポンスとともにポストデータを受け入れますが、Response イベントを使用してレスポンスをカスタマイズできます。このイベントでは、_request、_httpheaders、_response、_message の特別なアイテムが利用できます。指定した場合、コネクタは_response アイテムを通じてカスタムレスポンスが提供されることを想定します。
Response イベントを使用して、次の属性でカスタムアウトプットアイテムをプッシュすることもできます：
- Filename：フローに渡すアウトプットメッセージのファイル名。
- Data：フローに渡すメッセージに含めるデータ。バイナリデータの場合は、代わりにBase64Data 属性を使用します。
- Base64Data：フローに渡すメッセージに含めるBase64 エンコードされたデータ。
- HeaderNames#：フローに渡すメッセージに含めるヘッダー名のリスト。一致するインデックスでこれらのヘッダーの値を指定するには、HeaderValues 属性を使用します。
- HeaderValues#：フローに渡すメッセージに含めるヘッダー値のリスト。これらの値は、HeaderNames リスト内の一致するインデックスで定義されたヘッダー名に使用されます。
- Logs#：トランザクションのログに含めるログエントリのリスト。
レスポンスの例
カスタムのファイル名とヘッダーを付けて、Webhook リクエストのボディを含むファイルをフローに渡すには、Response イベント内のArcScript は次のようになります：
Response イベントでも同様のことができます。受信リクエスト上のヘッダーを、フローに渡すメッセージ上のヘッダーとして表面化するには、Response イベント内のArcScript は次のようになります：
Response イベントに設定すると、クライアントは次のようなリクエストを送信できます：