SPLATS Developers Site

Webhook概要

Webhookを利用してSPLATSで記録されたログを受け取ることができます。通知対象のログがSPLATSに記録されると、利用者が設定したWebhook URLにJSONオブジェクトが含まれたPOSTリクエストを送信します。
Webhookを利用することで、SPLATS APIを定期的に呼び出してログ検出を行う必要がなく、リアルタイムに通知を受け取ることができるようになります。

リクエスト

以下のリクエストヘッダーとリクエストボディで、設定されたWebhook URLにHTTP POSTリクエストをおこないます。
デバイスでログが記録されてすぐにSPLATSが受け取り、リクエストがおこなわれますが、ネットワークの状態によっては遅延が発生する場合があります。

リクエストヘッダー

名称	値/説明
X-Splats-ID	Webhookのリクエストごとに付与されるユニークID
X-Splats-Signature	シークレットトークンと Webhook のリクエストボディを使って計算された HMAC-SHA256 (設定がある場合のみ)
User-Agent	Splats-Webhook
Content-Type	application/json

　　　　名称　　　　

値/説明

X-Splats-ID

Webhookのリクエストごとに付与されるユニークID

X-Splats-Signature

シークレットトークンと Webhook のリクエストボディを使って計算された HMAC-SHA256 (設定がある場合のみ)

User-Agent

Splats-Webhook

Content-Type

application/json

リクエストボディ

下記の項目を持つJSONオブジェクトです。

フィールド名	タイプ	必須	説明
history_id	string	○	ログID
tenant_id	string	○	ログを記録したテナントのID
datetime	string	○	ログ記録日時 ISO 8601 拡張形式 "YYYY-MM-DDThh:mm:ss+09:00"
event	string	○	ログ内容(定数) 詳細は通知対象一覧を参照
event_name	string	○	ログ内容
status	string	○	ログ状態 occur：発生 restore：復旧
category	string	○	ログカテゴリー normal：通常 suspicious：不審 warning：不正 error：障害 emergency：緊急
device_id	string	○	ログを記録したデバイスのID
device_name	string	○	ログを記録したデバイスの名前
device_module	string	○	ログを記録したデバイスのモジュール control：パスコントローラー front_in：入室側リーダー front_out：退室側リーダー keybox：キーボックス
additional_info	object	○	ログに応じたオブジェクト以下の情報をログに応じて付与しますエリア情報 { "additional_info":{ "area":{ "from":{ "id": "string", # 退室側のエリアID "name": "string" # 退室側のエリア名 }, "to":{ "id": "string", # 入室側のエリアID "name": "string" # 入室側のエリア名 } } } } メンバー情報 { "additional_info":{ "member":{ "id": "string", # メンバーID "name": "string", # メンバー名 "code": "string" # メンバーコード } } } カギ情報 { "additional_info":{ "units":[ { "unit_no": "string", # カギナンバー "unit_name": "string" # カギ名 } ] } } カメラ情報 { "additional_info":{ "video": { "camera_name": "string", # カメラ名 "exists": "boolean" # 関連する動画があるかどうか } } }

フィールド名

タイプ

必須

説明

history_id

string　

○　

ログID

tenant_id

string　

○　

ログを記録したテナントのID

datetime

string

○

ログ記録日時 ISO 8601 拡張形式 "YYYY-MM-DDThh:mm:ss+09:00"

event

string

○

ログ内容(定数)
詳細は通知対象一覧を参照

event_name

string

○

ログ内容

status

string

○

ログ状態

occur：発生
restore：復旧

レスポンス

リクエストには常にステータスコード200を返してください。
リクエストが失敗しても、再送はおこなわれません。
リクエストには 10 秒以内に応答してください。超過した場合、エラーとして扱われます。
※10秒という値は変更される可能性があります。
リクエストが何らかの原因でエラーになった場合、通知エラーとして扱われます。通知エラーが頻発する場合は該当するWebhookの設定を無効化する場合があります。有効化する場合は再度SPLATS APIから設定を更新してください。

リクエストの署名検証

Webhook設定時に secret_token を指定すると、リクエストヘッダーのX-Splats-Signatureに secret_token とリクエストボディを使って計算されたHMAC-SHA256署名を付与します。

secret_token を使ってその署名を計算し、SPLATSから送信された署名と比較することで、リクエストの送信元がSPLATS であることを確認できます。

サンプルコード(Python)

import hmac
import hashlib

secret_token = {Webhook設定時に指定したsecret_token}
message = {リクエストボディ}

signature = hmac.new(secret_token.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()

サンプルコード(Ruby)

require 'openssl'

secret_token = {Webhook設定時に指定したsecret_token}
message = {リクエストボディ}

signature = OpenSSL::HMAC::hexdigest(OpenSSL::Digest::SHA256.new, secret_token, message)

Webhookの通知条件

設定した通知条件により、該当するログがSPLATSに記録されると、Webhook通知を受け取ることができます。

設定可能な通知条件

分類	通知条件	説明
ログ	[通常]カテゴリー (入室/退室、取出/保管のみ)	入室/退室、取出/保管のログ ※入室/退室はSPLATS PASSでのみ、取出/保管はSPLATS KEYでのみ記録されるログです　[通常]にカテゴリーするログでも入室/退室、取出/保管以外のログは通知しません
[不審]カテゴリー	「不審」にカテゴリーされるログ閉め忘れ、未入室、未開扉など
[不正]カテゴリー	「不正」にカテゴリーされるログ未登録、権限なし、権限時間外など
[障害]カテゴリー	「障害」にカテゴリーされるログ通信エラー、停電発生、機器異常など
[緊急]カテゴリー	「緊急」にカテゴリーされるログ非常解錠、こじ開けなど

分類

通知条件

説明

ログ

[通常]カテゴリー
(入室/退室、取出/保管のみ)

入室/退室、取出/保管のログ
※入室/退室はSPLATS PASSでのみ、取出/保管はSPLATS KEYでのみ記録されるログです
　[通常]にカテゴリーするログでも入室/退室、取出/保管以外のログは通知しません

[不審]カテゴリー

「不審」にカテゴリーされるログ
閉め忘れ、未入室、未開扉など

[不正]カテゴリー

「不正」にカテゴリーされるログ
未登録、権限なし、権限時間外など

[障害]カテゴリー

「障害」にカテゴリーされるログ
通信エラー、停電発生、機器異常など

[緊急]カテゴリー

「緊急」にカテゴリーされるログ
非常解錠、こじ開けなど

Webhookの設定方法

WebhookはSPLATSメンバーサイト、SPLATS APIのWebhook設定更新から設定することができます。
SPLATS APIから設定するためには「Tenant」スコープが必要となります。
設定は1テナントごとに1件の設定が可能です。