WEBHOOK

扉で起きたことを、そのまま御社のシステムへ。

解錠・施錠などの履歴が記録されると、WatchKey が指定の URL に JSON を送ります。受け取る仕組みを御社で用意すれば、予約・会員・勤怠システムへの連携や、チャットツールへの通知などに使えます。

設定の手順
届くデータ
設計のポイント

SETUP

設定の手順

管理画面からも API からも設定できます。ここでは API での手順を紹介します。

受信側の認証を用意する（任意）
Webhook に Bearer トークンを付けて送れます。受信側で照合すれば、WatchKey 以外からのリクエストを弾けます。
```
POST /api/notifications/webhook/options

{ "category": 1, "content": "<受信側で照合するトークン>" }
```
通知の設定を作る
送り先の URL を登録します。手順1の認証を使う場合は、その ID を指定します。
```
POST /api/notifications

{
  "category": "WEBHOOK",
  "url": "https://your-service.example/hooks/watchkey",
  "is_enabled": true,
  "option_id": "<OPTION_ID>"
}
```
主な項目のみ抜粋しています。category を MAIL にすると、メールで通知できます。
通知する出来事を選ぶ
履歴の種類（施錠、アプリ解錠、カード解錠など）を ID で指定します。ID の一覧は GET /api/history_types で取得できます。
```
PUT /api/notifications/{id}/events

[1, 90, 110]
```
対象の扉・利用者を絞る
PUT /api/notifications/{id}/doors で対象の扉を、PUT /api/notifications/{id}/users で対象の利用者を指定できます。

PAYLOAD

届くデータ

履歴が記録されると、次のような JSON を POST で送ります。

POST https://your-service.example/hooks/watchkey
Content-Type: application/json; charset=UTF-8
Authorization: Bearer <受信側のトークン>

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "category": 110,
  "category_name": "カード解錠",
  "input": "1234567890ABCDEF",
  "user": "234e5678-e89b-12d3-a456-426614174001",
  "user_name": "山田太郎",
  "device": "345e6789-e89b-12d3-a456-426614174002",
  "device_name": "玄関ドア",
  "door": "456e789a-e89b-12d3-a456-426614174003",
  "door_name": "1階エントランス",
  "door_group_name": "1階フロア",
  "recorded_at": "2025-12-02 13:21:42"
}

項目	内容
`id`	履歴の ID
`category`	履歴の種類の ID と名前
`input`	使われたカード番号など
`user`	利用者の ID と名前
`device` / `door`	機器・扉・ドアグループの ID と名前
`recorded_at`	記録された日時

DESIGN TIPS

設計のポイント

RETRY

定期的な取得と組み合わせる

Webhook は再送されません。受信側が止まっていた時間の分は、GET /api/histories で期間を指定して取り直す設計をおすすめします。

IDEMPOTENT

同じ履歴を二重に処理しない

Webhook と定期取得の両方で同じ履歴を受け取ることがあります。履歴の id で重複を判定してください。

FAST ACK

受け取ったらすぐ応答する

受信したら先に応答を返し、重い処理は後から行うと、取りこぼしを防げます。

扉で起きたことを、そのまま御社のシステムへ。

設定の手順

受信側の認証を用意する（任意）

通知の設定を作る

通知する出来事を選ぶ

対象の扉・利用者を絞る

届くデータ

設計のポイント

定期的な取得と組み合わせる

同じ履歴を二重に処理しない

受け取ったらすぐ応答する

まずは、無料ではじめてみる。