enonic-webhook-integrator

Enonic Webhook Integrator

手順

ステップ 1：Enonic XP プロジェクトを検出する

1. node scripts/find-enonic-targets.mjs . を実行して、ワークスペース内の Enonic XP プロジェクトのルートを特定します。
2. スクリプトが空の配列を返した場合は処理を中止し、Enonic XP プロジェクトが見つからなかったことを説明します。
3. 複数のプロジェクトが見つかった場合は、どのプロジェクトに統合するかを確認します。
4. gradle.properties（appName）または build.gradle からアプリケーションキーを特定します。

ステップ 2：統合の方向を判断する

1. タスクを次のいずれかに分類します：アウトバウンドイベントリスナー（XP が内部イベントに反応して外部システムを呼び出す）、アウトバウンド Webhook 設定（XP が組み込み設定を通じて Webhook ペイロードを送信する）、インバウンド Webhook エンドポイント（XP が外部システムからのペイロードを受信する）、または 混合（これらの組み合わせ）。
2. references/event-reference.md を読み、適切なイベントタイプ、リスナーパターン、フィルタリング方法を確認します。
3. タスクにアウトバウンド Webhook の設定またはインバウンド HTTP サービスエンドポイントが含まれる場合は、references/webhook-reference.md を読みます。

ステップ 3：アウトバウンドイベントリスナーを実装する（該当する場合）

1. ひな型として assets/event-listener.template.ts を読みます。
2. lib-event の listener() 関数を使用して、アプリケーションの main.ts（または main.js）コントローラーにイベントリスナーを登録します。
3. type パラメーターには、対象となるノードイベント（例：node.pushed、node.created、node.updated、node.deleted）に一致するパターンを指定します。
4. コールバック内で event.data.nodes[].path を確認し、パスでイベントをフィルタリングして、意図したコンテンツツリーだけを処理するようにします。
5. リスナーから外部 HTTP エンドポイントを呼び出す必要がある場合は、コールバック内で lib-httpClient の request() 関数を使用するか、バックグラウンドタスクに処理を委譲します。
6. 処理に時間がかかる場合は、イベントスレッドをブロックしないよう、イベントコールバックから lib-task の executeFunction() を使ってバックグラウンドタスクに処理を委譲します。
7. CDN の無効化、検索インデックスの再構築、通知の送信など、統合パターンの全例については references/examples.md を読みます。

ステップ 4：アウトバウンド Webhook を設定する（該当する場合）

1. com.enonic.xp.webhooks.cfg の設定形式について、references/webhook-reference.md を読みます。
2. 対象 URL とイベントタイプを指定した Webhook エントリーを含めて、XP_HOME/config/com.enonic.xp.webhooks.cfg にファイルを作成するか、既存のファイルを更新します。
3. 設定したイベントタイプが、意図したコンテンツのライフサイクルイベントと一致していることを確認します。
4. Webhook の送信先には HTTPS URL を使用します。
5. 実際のシークレット値を設定ファイルやソースコードに書き込まないでください。 説明的なプレースホルダートークン（例：REPLACE_WITH_CDN_SECRET）を使用し、実際の認証情報は別経路で置き換えるよう運用担当者に指示します。シークレットはファイルにコミットせず、安全なデプロイパイプライン、環境変数、またはシークレット管理ツールを通じて運用担当者が管理する必要があります。 ステップ 5：受信 Webhook エンドポイントを実装する（該当する場合）
6. 出発点となるひな形として、assets/http-service.template.ts を読みます。
7. src/main/resources/services/<serviceName>/<serviceName>.ts に HTTP サービスコントローラーを作成します。
8. req.body から受信した JSON ペイロードを解析する post(req) 関数をエクスポートします。
9. 解析する前に、妥当なサイズ制限（例：1 MB）を超えるペイロードを拒否します。
10. 処理の前に、必須フィールド、認証ヘッダー、または HMAC 署名を確認して、受信ペイロードを検証します。
11. 外部ペイロードのすべての文字列フィールドを、コンテンツ操作で使用する前にサニタイズします。空白をトリミングし、最大長を適用し、HTML／スクリプトコンテンツを除去またはエスケープし、パストラバーサルシーケンス（..、/、\）を含む値を拒否します。
12. 生のペイロードオブジェクトをコンテンツ API に渡すのではなく、想定されるフィールド名の許可リストを使用します。
13. 適切な HTTP ステータスコードを返します。成功時は 200、ペイロードの形式が不正な場合は 400、認証に失敗した場合は 401、ペイロードのサイズが大きすぎる場合は 413、予期しないエラーの場合は 500 を返します。
14. 受信ペイロードによってコンテンツの作成または変更が行われる場合は、適切な権限を確保するため、コンテキスト実行内で lib-content または lib-node API を使用します。サニタイズされていない外部の値を、コンテンツ名、パス、キーとして渡してはいけません。

ステップ 6：lib-task で非同期処理を連携する（該当する場合）

1. イベント処理または Webhook 処理に負荷の高い作業や時間のかかる作業が必要な場合は、lib-task の executeFunction() でラップします。
2. 長時間実行されるタスクから progress() で進捗を報告し、監視できるようにします。
3. タスクのイベントライフサイクル（task.submitted、task.updated、task.finished、task.failed）については、references/event-reference.md を読みます。

ステップ 7：連携を検証する

1. node scripts/find-enonic-targets.mjs . を実行し、プロジェクトが引き続き正しく解決されることを確認します。
2. アプリケーションの起動時に実行される main.ts または main.js ファイルで、イベントリスナーが登録されていることを確認します。
3. 外部向け HTTP 呼び出しで HTTPS が使用され、ネットワーク障害および 2xx 以外の応答に対するエラー処理が含まれていることを確認します。
4. 生成されたソースコードまたは設定ファイルに、実際のシークレット値、API キー、認証情報が含まれておらず、プレースホルダートークンのみが使用されていることを確認します。
5. 受信 Webhook エンドポイントで、コンテンツ API に渡す前に外部ペイロードのすべてのフィールドがサニタイズされ、許可リストに含まれていることを確認します。
6. Webhook 設定ファイルを作成した場合は、イベントタイプのパターンが意図したトリガーと一致していることを確認します。
7. ワークスペースのビルドを実行し、コンパイルエラーがないことを確認します。
8. イベントが発生しない場合、Webhook の配信に失敗する場合、または受信リクエストが拒否される場合は、references/troubleshooting.md を読みます。

エラー処理

• node scripts/find-enonic-targets.mjs . でプロジェクトが見つからない場合は、build.gradle が com.enonic.xp プラグインを参照していること、または src/main/resources/site/ ディレクトリが存在することを確認します。
• リスナーを登録した後もイベントが発生しない場合は、references/troubleshooting.md を読み、リスナーの登録場所、イベントタイプのパターン、クラスタースコープとローカルイベントスコープを確認します。
• 外部向け HTTP 呼び出しに失敗する場合は、接続先 URL、XP インスタンスからのネットワークアクセス、およびオペレーターがプレースホルダートークンを実際の認証情報に置き換えていることを確認します。
• 受信 Webhook リクエストが 404 を返す場合は、サービスコントローラーのパスが services/<name>/<name>.ts になっていること、およびアプリケーションがデプロイされていることを確認します。
• バックグラウンドタスクが失敗しても何も記録されない場合は、taskLib.list() を使ってタスクの状態を確認し、タスク関数内のエラーについてログを調べます。