SDI Webhook Bridge Service セットアップ手順
セットアップ手順
Step1: SDI Webhook Bridge Service をダウンロード
用途に応じて、以下のいずれかをダウンロードしてください。
ご案内
通常は Self-contained 版 をご利用ください。
Self-contained 版は .NET Runtime を同梱しているため、サーバーに .NET Runtime を別途インストールしなくても動作します。
Framework-dependent 版をご利用の場合は、サーバーに .NET 10 ASP.NET Core Runtime または .NET 10 Hosting Bundle が必要です。
Step2: ファイルを配置
ダウンロードした zip ファイルを任意のフォルダーに解凍します。
推奨配置先:
C:\SdiWebhookBridgeService\app
配置後、以下の実行ファイルが存在することを確認してください。
C:\SdiWebhookBridgeService\app\Sdi.WebhookBridgeService.exe
公開パッケージに含まれる主なファイル
Sdi.WebhookBridgeService.exe : サービス実行ファイル
appsettings.json : ASP.NET Core 設定ファイル
webhookservice.config.sample.xml : Webhook Service 設定サンプル
NOTICE.en.txt / NOTICE.ja.txt : 説明
Step3: CONFIG ファイルを作成
webhookservice.config.sample.xml をコピーして、webhookservice.config.xml を作成します。
copy C:\SdiWebhookBridgeService\app\webhookservice.config.sample.xml C:\SdiWebhookBridgeService\app\webhookservice.config.xml
作成した webhookservice.config.xml を編集します。
設定例:
<?xml version="1.0" encoding="utf-8"?>
<WebhookService>
<!-- Listening port for SDI Webhook Bridge Service. -->
<Server Port="8080" />
<Tenants>
<!--
Tenant name must match the "tenant" value in the incoming JSON request.
You can define multiple tenants when different API keys or event settings are required.
-->
<Tenant Name="DefaultTenant">
<!--
API key used for request authentication.
Clients must send this value in the HTTP header: X-API-Key.
-->
<ApiKey>replace-with-secret-api-key</ApiKey>
<Events>
<!--
Debounce mode:
Multiple requests for the same event are collected in memory for a short period,
then one Trigger File is created.
-->
<Event
Name="DataUpdated"
TriggerDirectory="C:\SDI\Triggers\DefaultTenant"
TriggerFileExtension="json"
TriggerFileNameTemplate="{event}_{yyyyMMdd_HHmmss}_{guid}"
TriggerMode="Debounce"
DebounceSeconds="60"
MaxWaitSeconds="300" />
<!--
Immediate mode:
A Trigger File is created every time a request is received.
-->
<Event
Name="DataCreated"
TriggerDirectory="C:\SDI\Triggers\DefaultTenant"
TriggerFileExtension="json"
TriggerFileNameTemplate="{event}_{yyyyMMdd_HHmmss}_{guid}"
TriggerMode="Immediate" />
</Events>
</Tenant>
</Tenants>
</WebhookService>
API Key について
<ApiKey> には本番用の十分に長い秘密値を設定してください。
サンプル値や初期値のまま公開環境で利用しないでください。
Step4: TriggerDirectory の権限を設定
TriggerDirectory には、SDI File Trigger が監視するフォルダーを指定します。
例:
C:\SDI\Triggers\DefaultTenant
SDI Webhook Bridge Service の実行ユーザーに、対象フォルダーへの書き込み権限を付与してください。
必要な権限:
.tmpファイルの作成- JSON 内容の書き込み
- Flush
.tmpから設定拡張子への rename
Trigger File の削除について
SDI Webhook Bridge Service は、完成済みの Trigger File を削除しません。
処理済み Trigger File の削除または移動は、SDI File Trigger 側で行うことを推奨します。
Step5: Windows Service としてインストール
5.1. 管理者権限でコマンドプロンプトを起動します。
5.2. 以下のコマンドを実行して、サービスをインストールします。
sc.exe create SdiWebhookBridgeService binPath= "C:\SdiWebhookBridgeService\app\Sdi.WebhookBridgeService.exe" DisplayName= "SDI Webhook Bridge Service" start= delayed-auto
5.3. サービスを起動します。
初回インストール直後はサービスが未起動のため、下記のコマンドで起動してください。
sc.exe start SdiWebhookBridgeService
5.4. サービス状態を確認します。
sc.exe query SdiWebhookBridgeService
Step6: Health Check
サービス起動後、以下のコマンドで起動確認を行います。
Invoke-WebRequest http://localhost:8080/health
正常な場合、HTTP 200 が返ります。
Step7: API アクセス仕様とテスト
7.1. Endpoint
POST http://localhost:8080/api/webhooks
7.2. HTTP Header
Content-Type: application/json
X-API-Key: replace-with-secret-api-key
7.3. Request Body
{
"tenant": "DefaultTenant",
"event": "DataUpdated",
"payload": {
"accountId": "001XXXXXXXXXXXX"
}
}
7.4. PowerShell でテスト
Invoke-WebRequest `
-Method POST `
-Uri "http://localhost:8080/api/webhooks" `
-Headers @{ "X-API-Key" = "replace-with-secret-api-key" } `
-ContentType "application/json" `
-Body '{"tenant":"DefaultTenant","event":"DataCreated","payload":{"id":"001XXXXXXXXXXXX"}}'
成功時のレスポンス:
{
"status": "accepted"
}
HTTP Status:
| Status | 内容 |
|---|---|
| 202 Accepted | Webhook を受け付けました。 |
| 400 Bad Request | tenant / event 不正、または Payload 検証エラーです。 |
| 401 Unauthorized | API Key が未指定、または不正です。 |
Trigger File 出力仕様
Immediate
Webhook 受信ごとに Trigger File を 1 つ作成します。
出力例:
{
"tenant": "DefaultTenant",
"event": "DataUpdated",
"payload": {
"accountId": "001XXXXXXXXXXXX"
}
}
Debounce
大量イベント抑制用のモードです。
一定期間内のイベントを集約し、Trigger File を 1 つだけ作成します。
出力例:
{
"tenant": "DefaultTenant",
"event": "DataUpdated",
"eventCount": 1532,
"firstReceived": "2026-06-08T12:00:00Z",
"lastReceived": "2026-06-08T12:04:58Z"
}
Debounce の注意点
Debounce 状態はメモリ上で保持されます。
サービス再起動時の状態消失、複数プロセス間での状態非共有は仕様です。
厳密なイベント配送保証が必要な場合は、Queue や DB などの外部永続化機構をご検討ください。
Trigger File 名と拡張子
TriggerFileExtension
出力ファイルの拡張子を指定できます。
例:
TriggerFileExtension="json"
TriggerFileExtension=".json"
TriggerFileExtension="txt"
TriggerFileExtension="trigger"
未指定の場合は trigger が使用されます。
TriggerFileNameTemplate
出力ファイル名のテンプレートを指定できます。
例:
TriggerFileNameTemplate="{event}_{yyyyMMdd_HHmmss}_{guid}"
利用可能なトークン:
| Token | 内容 |
|---|---|
{tenant} |
Tenant 名 |
{event} |
Event 名 |
{mode} |
TriggerMode |
{yyyyMMdd} |
UTC 日付 |
{yyyyMMdd_HHmmss} |
UTC タイムスタンプ |
{guid} |
一意識別子 |
{guid} は必須ではありません。
同名ファイルが既に存在する場合、既存ファイルを上書きせず _1, _2 のような suffix を付与します。
例:
DataUpdated.json
DataUpdated_1.json
DataUpdated_2.json
IIS Reverse Proxy 構成
IIS で HTTPS を終端し、SDI Webhook Bridge Service を Windows Service として localhost で動作させる構成を推奨します。
External System
-> IIS HTTPS endpoint
-> http://localhost:8080
-> Sdi.WebhookBridgeService.exe
-> TriggerDirectory
-> SDI File Trigger
IIS Reverse Proxy を利用する場合は、IIS に以下をインストールしてください。
- URL Rewrite
- Application Request Routing, ARR
Firewall 設定
外部公開は 80 / 443 のみにし、8080 は localhost または内部アクセスのみに制限することを推奨します。
トラブルシューティング
404 Not Found
URL が正しいか確認してください。
/api/webhooks
IIS Reverse Proxy を利用している場合は、IIS の転送先が http://localhost:8080 になっているか確認してください。
401 Unauthorized
X-API-Key ヘッダーが正しいか確認してください。
X-API-Key: replace-with-secret-api-key
CONFIG の <ApiKey> と一致している必要があります。
400 Bad Request
以下を確認してください。
tenantが指定されているかeventが指定されているか- CONFIG に Tenant が定義されているか
- Tenant 配下に Event が定義されているか
- Payload がセキュリティ検証で拒否されていないか
Trigger File が作成されない
以下を確認してください。
TriggerDirectoryが存在するか- サービス実行ユーザーに書き込み権限があるか
- ウイルス対策ソフトが
.tmpや.json/.triggerをブロックしていないか - Debounce mode の場合、
DebounceSecondsまたはMaxWaitSecondsが経過しているか