「Outgoing Webhooks」はSPIRE POSで処理が実行された際に、設定されたURL宛にデータを送信します。

Outgoing Webhooksアプリを設定する

Outgoing Webhooksの利用を開始するにはSPIREアプリストアから「Outgoing Webhooks」の設定を行う必要があります。

[設定] > [アプリストア]

アプリ一覧からOutgoing Webhooksを開きます。

アプリ設定画面でAdd subscriptionをクリックして新しくWebhookサブスクリプションを登録します。

Webhookサブスクリプションの設定を行います。

➊ 任意のWebhook名を入力します。

➋ Webhookを送信するURLを入力します。https://で始まるURLである必要があります。

➌ Webhookを送信するSPIREのイベントを選択します。

➍ Saveをクリックして設定を保存します。

Webhookサブスクリプションが追加されるとSecret Keyが設定され、自動的にOutgoing WebhooksアプリがSPIREに追加されます。

このSecret Keyは設定したエンドポイント側で署名する際に必要になります。

Secret KeyのコピーボタンをクリックするとクリップボードにSecret Keyがコピーされます。

Webhookのログを確認する

➊ Logsタブを開きます。

➋ 期間を選択して表示をクリックします。

➌ {...}をクリックします。

実際に送信されたペイロードなど詳細を確認することができます。

Webhookの受信側でセキュリティ保護する

Webhookの受信側では外部からデータが送られてきた際に、発行元が正しいか署名を検証して改ざんされていないことをチェックする必要があります。

Outgoing Webhookで送信される情報にはWebhookサブスクリプションの登録で生成されたSecret Keyを使い、SHA256ハッシュ関数を使用してHMACを計算した結果をbase64でエンコードした署名がX-Spire-Signature含まれています。

POST /receive HTTP/1.1
Host: webhook.com
Content-Type: application/json
User-Agent: Spire-Outgoing-Webhooks
X-Spire-Signature: x5dCXsF9wZ....h6TR5gIsp=
X-Timezone: Asia/Tokyo
X-Localization: ja

このヘッダー署名(X-Spire-Signature)の値と、送信先のURL + JSON形式のPayloadを結合した文字列を同様のSHA256で生成したHMACをbase64でエンコードした値と一致していることを確認する必要があります。

受信側ではヘッダー署名と、受け取った情報を使って計算した署名が一致している場合のみ処理を通すように設計してください。

Ruby

# 送られてきたURL + Payloadとシークレットキーを使ってHMAC署名を生成
calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.hexdigest('sha256', secret_key, webhook_url + payload))
# 比較して署名が一致していることを確認
is_valid = (header_hmac === calculated_hmac)

PHP

// 送られてきたURL + Payloadとシークレットキーを使ってHMAC署名を生成
$calculatedSignature = base64_encode(hash_hmac('sha256', $webhookUrl . $payload, $secretKey));
// 比較して署名が一致していることを確認
$isValid = ($headerSignature === $calculatedSignature);