Outgoing Webhook¶
[更新: 2022年12月08日]
1. サービスアダプタ作成¶
さくらのクラウドコントロールパネルより新規にサービスアダプタを作成します。
サービスアダプタの追加画面からOutgoing Webhookに必要な情報を入力します。
| 名前 | サービスアダプタを管理する名前を入力します。 |
| プロジェクト | サービスアダプタを接続するプロジェクトを選択します。 作成されたサービスアダプタは、ここで選択したプロジェクトに所属するSIMとのみ通信できます。 |
| サービスアダプタ | outgoing webhookを選択します。 |
| Payload URL | メッセージ送信先のURLを入力します。 ※ http/https から始まるURLを入力してください。 |
| シークレット | メッセージの改ざんチェックに使用するための、任意の文字列を設定します。 シークレットを設定した場合、リクエストに X-Sakura-Signature ヘッダが付与されています。 X-Sakura-Signature には、リクエストボディをメッセージ、シークレットをキーとするHMAC-SHA1の16進表記（アルファベットは小文字）が設定されています。 この値と手元で計算したハッシュ値を比較することでメッセージの改ざんをチェックできます。 シークレットを設定しなかった場合は X-Sakura-Signature ヘッダは付与されません。 |
各項目を入力し、「作成」ボタンをクリックするとサービスアダプタを作成できます。なお、入力した項目は後からでも変更ができます。
参考
双方向通信を行う Webアプリケーション実装例 にて、Outgoing Webhookを用いた作例を参照できます。
2. メッセージの受信¶
デバイスから送られたメッセージは、Payload URLに指定したURLにPOSTリクエストされます。
以下に、受信したリクエストボディの改ざんチェックをするプログラム例を示します。
SECRET の値は適宜書き換えてください。
<?php
define('SECRET', 'XXXXXX'); // サービスアダプタ管理画面で指定したシークレット
define('SIGNATURE_KEY', 'X-Sakura-Signature');
// リクエストボディを取得
$request_body = file_get_contents('php://input');
// 改ざんチェック
if (!verify_request_body($request_body)) {
// 改ざんされている
}
// チェック関数
function verify_request_body(string $request_body): bool {
if (SECRET === '') {
// シークレットが指定されていなければチェックしない（検証成功とみなす）
return true;
}
// ヘッダ内のハッシュ値を取得
$headers = getallheaders();
if (!array_key_exists(SIGNATURE_KEY, $headers)) {
// X-Sakura-Signature リクエストヘッダが設定されていなければ検証失敗
return false;
}
$header_signature = $headers[SIGNATURE_KEY];
// 手元でハッシュ値を計算
$calculated_signature = hash_hmac('sha1', $request_body, SECRET);
// 2つが一致すれば検証成功
return $header_signature === $calculated_signature;
}
参考