すべてのWebhookリクエストは、エンドポイントの署名シークレットで署名されます。リクエストを信頼する前に署名を確認することで、サーバーは実際にNotiondeskから送信され、途中で変更されていないイベントのみを処理するようになります。
tv1X-ND-Signature{t}.{raw body}v1始める前に
- エンドポイントを追加した際にコピーした署名シークレットが手元にあります。これは
nd_whsec_で始まります。紛失した場合は、ローテーションしてください。署名シークレットのローテーションについては、「署名シークレットのローテーション」を参照してください。
- 受信側は、JSON解析を行う前の、受信したリクエスト本文をそのままの状態で読み取ることができます。
署名の仕組み
各リクエストにはX-ND-Signatureヘッダーが含まれています。
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| 一部 | それは何なのか |
|---|---|
t | リクエストが送信された時点(1970年1月1日(UTC)からの秒数)。再試行ごとに新しいtが取得されます。 |
v1 | t、ピリオド、および生のリクエストボディのHMAC SHA-256を、署名シークレットで署名し、小文字の16進数で記述します。 |
リクエストを確認する
- リクエストボディをバイト列としてそのまま読み込んでください。最初に解析する必要はありません。
X-ND-Signatureヘッダーをカンマで分割し、tとv1を読み込みます。
- 署名付きテキストを作成します:
t、ピリオド、そして元のテキスト本体。たとえば、1794955939.{"id":"019a8f2e-...",...}のようになります。
- そのテキストに対して、
nd_whsec_を含む完全な署名秘密情報を使用して HMAC SHA-256 を計算し、小文字の 16 進数で書き出してください。
- 定数時間比較を使用して、結果を
v1と比較してください。
tがサーバーの時刻から 5 分以内であることを確認してください。
- いずれかのチェックが失敗した場合は、
400と応答してリクエストを無視します。すべてのチェックが成功した場合は、200と応答してイベントを処理します。
Node.js の例
これはNode.js 18以降とExpressで動作します。express.rawは、署名に必要な生のバイト列としてボディを保持します。
Pythonの例
これは Python 3.9 以降と Flask で動作します。request.get_data() は生のボディを返します。
署名シークレットをローテーションする
情報が漏洩した可能性がある場合、または紛失した場合は、秘密情報をローテーションしてください。
const crypto = require('crypto');
const express = require('express');
function verifyNotiondeskSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(header ?? '').split(',').map((part) => part.trim().split('=')),
);
if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest('hex');
const received = Buffer.from(parts.v1);
const computed = Buffer.from(expected);
return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}
const app = express();
app.post('/webhooks/notiondesk', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyNotiondeskSignature(
req.body,
req.get('X-ND-Signature'),
process.env.NOTIONDESK_WEBHOOK_SECRET,
);
if (!valid) return res.sendStatus(400);
res.sendStatus(200);
const event = JSON.parse(req.body);
console.log('Received', event.event, event.id);
});
app.listen(3000);import hashlib
import hmac
import os
import time
from flask import Flask, request
app = Flask(__name__)
def verify_notiondesk_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
try:
parts = dict(part.strip().split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
received = parts["v1"]
except (AttributeError, KeyError, ValueError):
return False
if abs(time.time() - timestamp) > tolerance:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received)
@app.post("/webhooks/notiondesk")
def notiondesk_webhook():
valid = verify_notiondesk_signature(
request.get_data(),
request.headers.get("X-ND-Signature", ""),
os.environ["NOTIONDESK_WEBHOOK_SECRET"],
)
if not valid:
return "", 400
event = request.get_json()
print("Received", event["event"], event["id"])
return "", 200- 設定 > 開発者 > Webhooksでエンドポイントを開きます。
- 「署名シークレット」の下にある「回転」をクリックし、確認のためもう一度「回転」をクリックします。
- 新しいシークレットをコピーしてサーバーに保存し、 「保存しました」をクリックします。
切り替え中にいくつかのリクエストが失敗した場合、1分後に新しいシークレットを使用して再試行されます。
よくある間違い
- 生のボディではなく、解析済みのJSONをチェックしてください。ボディを解析してテキストに戻すと、スペースやエスケープが変更されるため、署名が一致しなくなります。受信したバイト列を確認してから、解析してください。
- 間違ったシークレットを使用しています。各エンドポイントにはそれぞれ固有のシークレットがあります。
nd_whsec_を含む値全体を使用し、ローテーションした場合は最新の値を使用してください。
- サーバーの時計が間違っています。サーバーの時計が数分以上ずれていると、有効なリクエストでも古く見えてしまいます。NTPなどを使って時計を同期させてください。
- 単純な等価性チェックと比較します。Node.jsの
crypto.timingSafeEqualや Python のhmac.compare_digestのような定数時間比較を使用してください。
よくある質問
5分以上前のリクエストを拒否する理由は?
キャプチャされたリクエストは、後で再度サーバーに送信される可能性があります。t をチェックすることで、その送信時間を短く制限できます。再試行のたびに新しい t が署名されるため、再試行も成功します。
テストイベントは署名されていますか?
はい。エンドポイントページの「テストイベントの送信」をクリックして、検証コードを確認してください。 「最近の配信」に「200」と表示されていれば、テストは成功です。
署名の秘密をもう一度見せてもらえますか?
いいえ。エンドポイントを追加したり、シークレットをローテーションしたりする際に一度だけ表示されます。エンドポイントページには、最初の数文字のみが表示されます。
私のエンドポイントはすべて、1つの秘密鍵を共有していますか?
いいえ。各エンドポイントには独自の署名シークレットがあるため、各リクエストを送信先のエンドポイントのシークレットと照合して検証してください。