Incoming Webhook

[更新: 2022年3月24日]

一部のデータフォーマットが変更されておりますので、本マニュアルも対応いたしました。

1. サービスアダプタ作成

さくらのクラウドコントロールパネルより新規にIncoming Webhookサービスアダプタを作成します。

サービスアダプタの追加画面からIncoming Webhookに必要な情報を入力します。

Incoming Webhook サービスアダプタ入力項目
名前 サービスアダプタを管理する名前を入力します。
プロジェクト サービスアダプタを接続するプロジェクトを選択します。
作成されたサービスアダプタは、ここで選択したプロジェクトに所属するSIMとのみ通信できます。
サービスアダプタ incoming webhookを選択します。
シークレット 任意に文字列を設定します。Incoming WebhookのURLへ届いたメッセージをIoTクラウドコア側でメッセージの検証を行い、メッセージの改ざんなどを防止します。
リクエストボディをメッセージ、Secret に入力した文字をキーとするHMAC-SHA1を計算し、X-Sakura-Signatureヘッダとして、リクエストを送信してください。

各項目を入力し、「作成」ボタンをクリックするとサービスアダプタを作成できます。なお、入力した項目は後からでも変更ができます。

2. メッセージの送信

Incoming Webhookサービスアダプタでデバイス方向へメッセージを送信します。

例としてdata.jsonというファイルを準備し、以下のjsonメッセージを記載します。 その際、 <device_id> は適宜書き換えます、 device_id はプロジェクトのSIM一覧画面から確認することができます。

{
   "device_id":"<device_id>",
   "type":"object",
   "payload":[
      {
         "type":"int32",
         "tag":"FF",
         "value":15
      },
      {
         "type":"float64",
         "tag":"00",
         "value":3.141592653589793
      }
   ]
}

メッセージデータを送信する前に末尾の改行コードを削除します。

$ sed -i -z 's/\n//g' data.json

また、シークレットを設定している場合リクエストボディをメッセージとしてHMAC-SHA1を計算します。 <secret>は適宜書き換えます。

$ cat data.json | openssl dgst -sha1 -hmac "<secret>"
(stdin)= xxxxxx

上記のHMAC-SHA1を X-Sakura-Signature ヘッダに入れて、POSTリクエストを送ります。 <token>は適宜書き換えます。

正しく送信ができた場合、サービスアダプタはnotifyタイプのデータを応答します。

curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://incoming.sipf.iot.sakura.ad.jp/v0/<token>'
{"device_id":"<device_id>","type":"notify","id":"xxxxxxxxxxxxxxxx"}

シークレットに誤りあり送信が失敗した場合、サービスアダプタはerrorタイプのデータを応答します。

curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://incoming.sipf.iot.sakura.ad.jp/v0/<token>'
{"device_id":"<device_id>","type":"error","datetime":"<datetime>>","payload":{"error":"Invalid Signature","detail":"invalid signature"}}