Убедитесь, что веб-хук исходит от Notiondesk

Проверьте заголовок X-ND-Signature в запросах веб-перехватчика Notiondesk с использованием вашего секретного ключа подписи, используя проверенные примеры на Node.js и Python.

2 мин чтения

Каждый запрос веб-хука подписывается секретным ключом подписи вашей конечной точки. Проверьте подпись, прежде чем доверять запросу, чтобы ваш сервер обрабатывал только те события, которые действительно поступают из Notiondesk и не были изменены в процессе обработки.

Быстрый способ: прочитать заголовок, вычислить HMAC SHA-256 с использованием вашего секретного ключа подписи, сравнить его с запросами старше 5 минут и отклонить их.tv1X-ND-Signature{t}.{raw body}v1

Прежде чем начать

  • Получатель может прочитать тело запроса в том виде, в котором оно поступило, до какого-либо анализа JSON.

Как работает подпись

Каждый запрос имеет заголовок X-ND-Signature:

X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb
Часть Что это такое
tВремя отправки запроса, в секундах с 1 января 1970 г. (UTC). Каждая повторная попытка получает новый t
v1HMAC SHA-256 для t, точка и исходное тело запроса, подписанное вашим секретным ключом и записанное в шестнадцатеричном формате строчными буквами.

Подтвердите запрос

  1. Считывайте необработанное тело запроса как байты. Не анализируйте его предварительно.
  1. Разделите заголовок X-ND-Signature по запятым и прочтите t и v1.
  1. Создайте подписанный текст: t, точка, а затем основной текст. Например, 1794955939.{"id":"019a8f2e-...",...}.
  1. Вычислите HMAC SHA-256 этого текста, используя ваш полный секретный ключ подписи, включая nd_whsec_, и запишите его в шестнадцатеричном формате в нижнем регистре.
  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. Откройте конечную точку в разделе «Настройки» > «Разработчики» > «Веб-перехватчики» .
  1. В разделе «Секретный ключ подписи» нажмите «Повернуть» , а затем «Повернуть еще раз» для подтверждения.
  1. Скопируйте новый секретный ключ, сохраните его на своем сервере, а затем нажмите «Я сохранил» .
Старый секретный ключ перестаёт работать сразу же. Каждый запрос, отправленный после смены ключа, включая повторные попытки обработки более ранних событий, подписывается новым секретным ключом, поэтому обновите свой сервер одновременно с этим.

Если во время переключения несколько запросов не удастся, они будут повторены через 1 минуту с использованием нового секретного ключа.

Распространенные ошибки

  • Проверяем разобранный JSON вместо исходного тела запроса. Разбор тела запроса и его преобразование обратно в текст изменяет пробелы и экранирование, поэтому подпись больше не совпадает. Проверьте полученные байты, затем выполните разбор.
  • Используется неправильный секретный ключ. У каждой конечной точки свой собственный секретный ключ. Используйте всё значение целиком, включая nd_whsec_, и последнее, если вы его изменили.
  • Неправильные серверные часы. Если часы вашего сервера отстают более чем на несколько минут, действительные запросы будут выглядеть слишком старыми. Поддерживайте синхронизацию часов, например, с NTP.
  • Сравнение с помощью простой проверки на равенство. Используйте сравнение с постоянным временем выполнения, например, crypto.timingSafeEqual в Node.js или hmac.compare_digest в Python.

Часто задаваемые вопросы

Почему отклоняются запросы старше 5 минут?

Перехваченный запрос может быть отправлен на ваш сервер повторно позже. Проверка параметра t ограничивает это коротким промежутком времени. Каждая повторная попытка подписывается новым параметром t, поэтому повторные попытки по-прежнему проходят успешно.

Подписано ли тестовое событие?

Да. Нажмите «Отправить тестовое событие» на странице конечной точки, чтобы проверить свой проверочный код. 200 в разделе «Недавние доставки» означает, что проверка пройдена успешно.

Можно мне еще раз посмотреть секрет подписания?

Нет. Он отображается один раз, при добавлении конечной точки или изменении секретного ключа. На странице конечной точки отображаются только первые символы.

Все ли мои конечные точки имеют один общий секретный ключ?

Нет. У каждой конечной точки свой собственный секретный ключ для подписи, поэтому проверяйте каждый запрос по секретному ключу той конечной точки, на которую он был отправлен.

Связанные статьи

Эта страница была полезной?

Still need help? Ask us