Incoming Webhook¶

[更新: 2023年06月29日]

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

さくらのクラウドコントロールパネルより新規にIncoming Webhookサービスアダプタを作成します。サービスアダプタの追加画面からIncoming Webhookに必要な情報を入力します。

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

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

参考

双方向通信を行う Webアプリケーション実装例にて、Incoming Webhookを用いた作例を参照できます。

2. メッセージの送信 ¶

Incoming Webhook用のURLにデータを送信することで、デバイス方向へメッセージを送信できます。 URLは暗号化プロトコル（HTTPS）のみ対応しています。

例として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"}}

参考

データフォーマット

3. エラーレスポンスの一覧 ¶

Incoming Webhook に対してリクエストに誤りがあった場合、以下のようなエラーが返されます。

エラーステータスコードとレスポンスの一覧¶
HTTP Status	エラーの原因と対処法
400(Bad Request)	正しいメッセージフォーマットでリクエストてください
401(Unauthorized)	正しいトークンを含めてアクセスしてください
403(Forbidden)	デバイスID がサービスアダプタと連携されていません
404(Not Found)	デバイス、もしくはデバイスに対するサービスアダプタが見つかりません
405(MethodNotAllowed)	POST 以外の HTTP Request は許可されておりません
422(Unprocessable Entity)	JSON の形式が間違っています。正しいメッセージフォーマットでリクエストしてください
429(Too Many Request)	プラットフォームへのリクエストが多すぎます。時間をおいてリクエストしてください
500(Internal Server Error)	内部エラーです。時間をおいてリクエストしてください

Incoming Webhook¶

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

2. メッセージの送信¶

3. エラーレスポンスの一覧¶

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

2. メッセージの送信 ¶

3. エラーレスポンスの一覧 ¶