Notiondesk からウェブフックが送信されていることを確認してください。

署名シークレットを使用して、Notiondesk ウェブフックリクエストの X-ND-Signature ヘッダーを確認してください。テスト済みの Node.js および Python の例も含まれています。

2 分で読めます

すべてのWebhookリクエストは、エンドポイントの署名シークレットで署名されます。リクエストを信頼する前に署名を確認することで、サーバーは実際にNotiondeskから送信され、途中で変更されていないイベントのみを処理するようになります。

簡単な手順:ヘッダーから読み取り、署名シークレットを使用してHMAC SHA-256を計算し、それをと比較して、5分以上前のリクエストを拒否します。tv1X-ND-Signature{t}.{raw body}v1

始める前に

  • 受信側は、JSON解析を行う前の、受信したリクエスト本文をそのままの状態で読み取ることができます。

署名の仕組み

各リクエストにはX-ND-Signatureヘッダーが含まれています。

X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb
一部それは何なのか
tリクエストが送信された時点(1970年1月1日(UTC)からの秒数)。再試行ごとに新しいtが取得されます。
v1t、ピリオド、および生のリクエストボディのHMAC SHA-256を、署名シークレットで署名し、小文字の16進数で記述します。

リクエストを確認する

  1. リクエストボディをバイト列としてそのまま読み込んでください。最初に解析する必要はありません。
  1. X-ND-Signature ヘッダーをカンマで分割し、t と v1 を読み込みます。
  1. 署名付きテキストを作成します: t、ピリオド、そして元のテキスト本体。たとえば、1794955939.{"id":"019a8f2e-...",...} のようになります。
  1. そのテキストに対して、nd_whsec_ を含む完全な署名秘密情報を使用して HMAC SHA-256 を計算し、小文字の 16 進数で書き出してください。
  1. 定数時間比較を使用して、結果をv1と比較してください。
  1. t がサーバーの時刻から 5 分以内であることを確認してください。
  1. いずれかのチェックが失敗した場合は、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
  1. 設定 > 開発者 > Webhooksでエンドポイントを開きます。
  1. 「署名シークレット」の下にある「回転」をクリックし、確認のためもう一度「回転」をクリックします。
  1. 新しいシークレットをコピーしてサーバーに保存し、 「保存しました」をクリックします。
古いシークレットはすぐに無効になります。ローテーション後に送信されるすべてのリクエスト(以前のイベントの再試行を含む)は新しいシークレットで署名されるため、サーバーも同時に更新してください。

切り替え中にいくつかのリクエストが失敗した場合、1分後に新しいシークレットを使用して再試行されます。

よくある間違い

  • 生のボディではなく、解析済みのJSONをチェックしてください。ボディを解析してテキストに戻すと、スペースやエスケープが変更されるため、署名が一致しなくなります。受信したバイト列を確認してから、解析してください。
  • 間違ったシークレットを使用しています。各エンドポイントにはそれぞれ固有のシークレットがあります。nd_whsec_ を含む値全体を使用し、ローテーションした場合は最新の値を使用してください。
  • サーバーの時計が間違っています。サーバーの時計が数分以上ずれていると、有効なリクエストでも古く見えてしまいます。NTPなどを使って時計を同期させてください。
  • 単純な等価性チェックと比較します。Node.jsの crypto.timingSafeEqual や Python の hmac.compare_digest のような定数時間比較を使用してください。

よくある質問

5分以上前のリクエストを拒否する理由は?

キャプチャされたリクエストは、後で再度サーバーに送信される可能性があります。t をチェックすることで、その送信時間を短く制限できます。再試行のたびに新しい t が署名されるため、再試行も成功します。

テストイベントは署名されていますか?

はい。エンドポイントページの「テストイベントの送信」をクリックして、検証コードを確認してください。 「最近の配信」に「200」と表示されていれば、テストは成功です。

署名の秘密をもう一度見せてもらえますか?

いいえ。エンドポイントを追加したり、シークレットをローテーションしたりする際に一度だけ表示されます。エンドポイントページには、最初の数文字のみが表示されます。

私のエンドポイントはすべて、1つの秘密鍵を共有していますか?

いいえ。各エンドポイントには独自の署名シークレットがあるため、各リクエストを送信先のエンドポイントのシークレットと照合して検証してください。

関連する記事

このページは役に立ちましたか?

Still need help? Ask us