Akerunコントローラーからwebhookする

初めに

みなさんこんにちは、naritakuです。本日はAkerun Adveent Calender 2023 16日目の記事です。前回のAkerunコントローラーのスマートプラグ化に引き続き、Akerunコントローラーの改造第二弾です。

Akerunコントローラーは既設の電気制御のドアやゲートに簡易工事だけで設置し、直接制御できるスマートロックです。

Akerunコントローラーはドアの錠ともネットワークとも有線で接続されています。そのため、ゲートウェイ端末とのBLE通信必要とするAkerun Proに比べ、よりリアルタイムに遠隔から施錠、解錠できる利点があります。

Akerunコントローラーの場合

sequenceDiagram

actor User
participant ctl as Akerunコントローラー


User->>ctl:遠隔解錠のリクエスト
activate ctl
      ctl->>ctl: 繋がれた錠を解錠
deactivate ctl

Akerun Proの場合

sequenceDiagram

actor User
participant remote as Akerun Remote
participant akerun as Akerun Pro


User->>remote:遠隔解錠のリクエスト


  activate remote
      remote->>akerun: BLE通信による解錠リクエスト
  deactivate remote
  activate akerun
      akerun->>akerun: サムターンを回して解錠
 deactivate akerun

素早く応答できるなら、「扉が開いたことに連動してリアルタイムにXXXがしたい！」といったご要望にも応えたいですよね。ということで、Akerunコントローラーの開閉をリアルタイムに通知すべく、webhookを仕掛けて遊んでみます。

やってみる

今回やりたいこと

Akerunコントローラーは既存の機能として開閉後に履歴のアップロードをしています。開閉を検知したらwebhookとして事前に登録したURLにデータを渡したいです。

sequenceDiagram

actor User
participant ctl as Akerunコントローラー
participant Server as 外部のテスト用のサーバー

User->>ctl: 解錠リクエスト
activate ctl
    ctl->>ctl: 認証
    opt 認証成功
        ctl->>ctl: 解錠
        ctl->>Server: webhook!
    end
deactivate ctl

webhookとは？

HTTPリクエストを使って他のサービスにイベントの発生を伝える仕組みです。

単純なHTTPリクエストなので、扱える環境が幅広い。
ポーリングに比べ、効率的に通信できる

などの利点があります。

詳細は

が勉強になりました。

webhookのあるあるを知りたい

webhookの雰囲気を掴むため、webhookの機能を提供しているサービスのドキュメントを眺めてみます。outgoing webhookと呼ばれている、ユーザーの指定したサーバーへ各webサービスから通知する方向のサービスをいくつか記載します。 LINEやGitHub、PayPayなど、生活に密着した様々なサービスが提供されていますね。

サービス	できること	ドキュメント	なりすましの対策としておすすめしていること
LINE	botアカウントへの友だち追加やメッセージ送信などのイベント通知	メッセージ（Webhook）を受信する	リクエストボディーのHMAC-SHA256によるハッシュ値とリクエストヘッダーのx-line-signatureとして通知される署名を使ったHMACの検証
GitHub	事前にサブスクライブしたGitHubで発生するイベント通知	Webhook のイベントとペイロード	Webhook の使用に関するベストプラクティス
Meta	MessengerやInstagram,WhatsAppなど各種サービスのイベント通知	スタートガイド - Meta Webhooks	SHA256のハッシュ値での認証
PayPay	支払い関連のイベント通知	PAYPAY API docs	IPアドレスのホワイトリスト登録
Paidy	決済フローに進展があったことの通知	Webhookとは	\|通知のあった決済IDを使い、APIサーバーへ詳細な決済情報を再度問い合わせ検証

webhook自体は簡単に通知を送信できてしまうため、なりすましの対策は各サービスともに考えられています。また、webhookを受信できなかった場合のリカバリーとして webhookの再配信をする仕組み等もあるようです。

webhookを使ったサービスでも、求められる要件で必要とされる機能は変わりそうですね。実際にAkerun入退室管理システムとしてwebhookの通知をする場合は、Akerun APIの履歴取得API を補完するような機能にできると良さそうです。

錠の開閉をwebhookで通知してみる

先ほどのoutgoing webhookに対して、incomming webhookと呼ばれている、ユーザーから各サービスのエンドポイントへ通知するwebhookのサービスを提供しているサービスもいくつか探して連結させてみます。

ワークフロー系のツールやチャットツールが多いですね

サービス	できること	ドキュメント
GoogleChat	チャットへの通知	Google Chat アプリを Webhook として作成する
Slack	Slack ワークフローの発火	Webhook で開始するワークフローを作成する
n8n	ワークフロー自動化ツールのトリガー	ウェブフック｜n8n ドキュメント

試しにslack workflowに錠の開閉を通知してみます。 Akerun APIと共通になるいくつかのパラメータを変数として通知できるようにしてみます。

{
    action: 'unlock' または 'lock',
    akerun_id: 対象のAkerunコントローラーのID,
    accessed_at: 入退室の時間（ISO 8601形式）,
}

slack側で設定していきます

条件分岐など、細かい設定はできませんが、変数をメッセージに埋め込めば、毎回異なるメッセージを通知できます。

まずはcurlでデータを渡して動作確認です

curl -X POST -H "Content-Type: application/json" -d '{
    "action": "lock",
    "akerun_id": "R12XXXXXXXX",
    "accessed_at": "'$(date -u +'%Y-%m-%dT%H:%M:%SZ')'"
}' 'https://hooks.slack.com/triggers/XXXXXXXXX/YYYYYYYYYYYYY/ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ';