ホーム > ドキュメント > Webhook の利用方法

Webhook の利用方法

概要

『奉行クラウド』のデータの登録・修正・削除のイベントに応じて、設定されている通知先の URL にイベント情報を送信する仕組みです。
リアルタイムに、『奉行クラウド』のデータの変更を開発するアプリケーションで検知できるため、日次バッチ処理など定期的にデータを取得することなく、効率よく変更内容に応じた連携が実現できます。

Webhook を利用するための設定方法

『奉行クラウド』の Webhook を利用するための設定は、2つ方法があります。

設定可能な Webhook イベントは、Webhook イベントの一覧をご参照ください。

Webhook 通知設定の登録 API で設定する方法

Webhook 通知設定の登録 API で登録できます。
API で登録した設定は、『管理ポータル』の［連携アプリケーション］メニューに表示されます。
設定を変更する場合には、貴社アプリケーションから Webhook 通知設定の登録 API を改めて実行するか、『管理ポータル』の［連携アプリケーション］メニューから手動で実行できます。

Request Body プロパティ一覧

WebhookSettingDetail

利用可能なイベントキー

Webhook イベントキー

eventKeys にイベントキーの文字列を指定します。

{
    "settings" : 
        [ 
            { 
                … 
                "eventKeys": [
                    "GL_AccountItem_Created", 
                    "GL_AccountItem_Updated", 
                    "GL_AccountItem_Deleted" 
                ] 
            } 
        ] 
}

内訳項目がある Webhook イベントキー

内訳項目があるイベントキーでは、「.」で DivisionID を指定することで対象のイベントの内訳を指定します。
HM_EmployeeHistoryDivision_Created などは、「HM_EmployeeHistoryDivision_Created.{DivisionID}」という指定をします。

{
    "settings" : 
        [ 
            { 
                … 
                "eventKeys": [
                    "HM_EmployeeHistoryDivision_Created.1001",
                    "HM_EmployeeHistoryDivision_Created.1002"
                ] 
             } 
         ] 
}

Webhook を利用した連携フロー

API か『管理ポータル』のいずれかで、Webhook の通知設定を登録します。

『奉行クラウド』でイベント発生後、Webhook の通知設定で指定した、通知先の URL に POST リクエストが送信されます。
以下のような POST リクエストが送信されます。

Request

POST https://........ 
Accept: application/json 
Accept-Charset: 
utf-8 X-OBC-Secret: ****************************** 
Content-Type: application/json; charset=utf-8 
{
    [ 
        { 
            "id": "52A4C69D-9641-4147-860D-FFA5C207FDAB", 
            "eventkey": "EventKey", 
            "eventvalues": {
                "Key": "Value" 
            }, 
            "eventdatetime": "2019-01-01T00:00:00.000000Z" 
        }, 
        { ... }
    ] 
}

Request Header

Request Body プロパティ一覧

POST リクエスト受信後の処理を実行します。
リクエスト受信後、速やかに、受信完了の結果（ステータスコード：200）を返却してください。

Webhook 通知のリトライ

開発するアプリケーションで Webhook のリクエストを受信したのち、速やかに、受信完了の結果（ステータスコード：200）を返却してください。
リクエストの成功を確認できない場合、Webhook は通知のリトライをします。

「ステータスコード：200」以外のレスポンスを検知した場合、送信失敗とみなして、Webhook をリトライします。
リトライ処理は、約 3 日間で最大 17 回施行します。
リトライ回数の上限に達して送信失敗した場合は、対象の Webhook 通知設定が無効になります。
参考
無効になった Webhook 通知設定は、『管理ポータル』の［連携アプリケーション］メニューから有効化できます。

Webhook 通知の正当性

Webhook が、『奉行クラウド』の正当な通知元サーバーから通知された情報かどうかを検証することで、通知されたデータの正当性を確認し、安全に利用できます。
奉行クラウド Webhook を利用する場合には、正当性を検証したうえでご利用ください。

通知元サーバーの IP アドレス

『奉行クラウド』の正当な通知元サーバーの IP アドレスを固定にしています。
IP アドレスを検証することで、奉行クラウド Webhook が通知したリクエストという正当性を確認できます。

アプリケーション開発環境

https://gw-demo.obc.jp

お客様環境

https://gw.obc.jp

Webhook 通知設定のシークレット

Webhook のリクエストヘッダー「X-OBC-Secret」に、Webhook 通知設定で事前登録した固定文字列を付加して通知します。
この事前設定した値を検証することで、奉行クラウド Webhook が通知したリクエストという正当性を確認できます。

以下のように、リクエストヘッダー「X-OBC-Secret」に値が指定されます。

Request

POST https://........ 
Accept: application/json 
Accept-Charset: utf-8 
X-OBC-Secret: ******************************（平文）
Content-Type: application/json; charset=utf-8 
{
 ・・・ 
}

プロトコル

HTTPS（TLS 1.2）をサポートしています。

Webhook 設定テンプレート

Webhook 通知設定の登録 API を使わずに、お客様に Webhook の設定をご案内する場合の、設定テンプレートがあります。
設定テンプレートを、こちらからダウンロードし、必要事項を記載の上、お客様にご案内ください。