Каждый запрос веб-хука подписывается секретным ключом подписи вашей конечной точки. Проверьте подпись, прежде чем доверять запросу, чтобы ваш сервер обрабатывал только те события, которые действительно поступают из Notiondesk и не были изменены в процессе обработки.
tv1X-ND-Signature{t}.{raw body}v1Прежде чем начать
- У вас есть секретный ключ подписи, который вы скопировали при добавлении конечной точки. Он начинается с
nd_whsec_. Если вы его потеряли, замените его. См. раздел «Замена секретного ключа подписи» .
- Получатель может прочитать тело запроса в том виде, в котором оно поступило, до какого-либо анализа JSON.
Как работает подпись
Каждый запрос имеет заголовок X-ND-Signature:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Часть | Что это такое |
|---|---|
t | Время отправки запроса, в секундах с 1 января 1970 г. (UTC). Каждая повторная попытка получает новый t |
v1 | HMAC SHA-256 для t, точка и исходное тело запроса, подписанное вашим секретным ключом и записанное в шестнадцатеричном формате строчными буквами. |
Подтвердите запрос
- Считывайте необработанное тело запроса как байты. Не анализируйте его предварительно.
- Разделите заголовок
X-ND-Signatureпо запятым и прочтитеtиv1.
- Создайте подписанный текст:
t, точка, а затем основной текст. Например,1794955939.{"id":"019a8f2e-...",...}.
- Вычислите HMAC SHA-256 этого текста, используя ваш полный секретный ключ подписи, включая
nd_whsec_, и запишите его в шестнадцатеричном формате в нижнем регистре.
- Сравните свой результат с
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- Откройте конечную точку в разделе «Настройки» > «Разработчики» > «Веб-перехватчики» .
- В разделе «Секретный ключ подписи» нажмите «Повернуть» , а затем «Повернуть еще раз» для подтверждения.
- Скопируйте новый секретный ключ, сохраните его на своем сервере, а затем нажмите «Я сохранил» .
Если во время переключения несколько запросов не удастся, они будут повторены через 1 минуту с использованием нового секретного ключа.
Распространенные ошибки
- Проверяем разобранный JSON вместо исходного тела запроса. Разбор тела запроса и его преобразование обратно в текст изменяет пробелы и экранирование, поэтому подпись больше не совпадает. Проверьте полученные байты, затем выполните разбор.
- Используется неправильный секретный ключ. У каждой конечной точки свой собственный секретный ключ. Используйте всё значение целиком, включая
nd_whsec_, и последнее, если вы его изменили.
- Неправильные серверные часы. Если часы вашего сервера отстают более чем на несколько минут, действительные запросы будут выглядеть слишком старыми. Поддерживайте синхронизацию часов, например, с NTP.
- Сравнение с помощью простой проверки на равенство. Используйте сравнение с постоянным временем выполнения, например,
crypto.timingSafeEqualв Node.js илиhmac.compare_digestв Python.
Часто задаваемые вопросы
Почему отклоняются запросы старше 5 минут?
Перехваченный запрос может быть отправлен на ваш сервер повторно позже. Проверка параметра t ограничивает это коротким промежутком времени. Каждая повторная попытка подписывается новым параметром t, поэтому повторные попытки по-прежнему проходят успешно.
Подписано ли тестовое событие?
Да. Нажмите «Отправить тестовое событие» на странице конечной точки, чтобы проверить свой проверочный код. 200 в разделе «Недавние доставки» означает, что проверка пройдена успешно.
Можно мне еще раз посмотреть секрет подписания?
Нет. Он отображается один раз, при добавлении конечной точки или изменении секретного ключа. На странице конечной точки отображаются только первые символы.
Все ли мои конечные точки имеют один общий секретный ключ?
Нет. У каждой конечной точки свой собственный секретный ключ для подписи, поэтому проверяйте каждый запрос по секретному ключу той конечной точки, на которую он был отправлен.