כל בקשת webhook נחתמת עם סוד החתימה של נקודת הקצה שלך. בדוק את החתימה לפני שאתה נותן אמון בבקשה, כך שהשרת שלך יפעל רק על אירועים שמגיעים באמת מ-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 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 .
- תחת סוד חתימה , לחץ על סובב , ולאחר מכן סובב שוב כדי לאשר.
- העתיקו את הסוד החדש, אחסן אותו בשרת שלכם ולאחר מכן לחצו על שמרתי אותו .
אם מספר בקשות נכשלות בזמן המעבר, הן יתבצעו שוב לאחר דקה עם הסוד החדש.
טעויות נפוצות
- בדיקת JSON מנותח במקום גוף הקובץ הגולמי. ניתוח הגוף והפיכתו חזרה לטקסט משנה את המרווח ואת תווי ה-escape, כך שהחתימה כבר לא תואמת. ודאו את הבייטים שקיבלת, ולאחר מכן נתחו.
- שימוש בסוד שגוי. לכל נקודת קצה יש סוד משלה. השתמש בערך המלא, כולל
nd_whsec_, ובערך העדכני ביותר אם סובבת אותו.
- שעון שרת שגוי. אם שעון השרת שלך שגוי ביותר מכמה דקות, בקשות תקפות נראות ישנות מדי. שמור על סנכרון השעון, לדוגמה עם NTP.
- השוואה עם בדיקת שוויון פשוטה. השתמשו בהשוואה בזמן קבוע, כמו
crypto.timingSafeEqualב-Node.js אוhmac.compare_digestבפייתון.
שאלות נפוצות
למה לדחות בקשות בנות יותר מ-5 דקות?
בקשה שנלכדה עלולה להישלח שוב לשרת שלך מאוחר יותר. בדיקת t מגבילה זאת לחלון זמן קצר. כל ניסיון חוזר נחתם שוב עם t חדש, כך שניסיונות חוזרים עדיין יעברו.
האם אירוע הבדיקה חתום?
כן. לחץ על שלח אירוע בדיקה בדף נקודת הקצה כדי לבדוק את קוד האימות שלך. 200 תחת משלוחים אחרונים פירושו שההזמנה עברה.
האם אוכל לראות שוב את סוד החתימה?
לא. הוא מוצג פעם אחת, כאשר מוסיפים את נקודת הקצה או מסובבים את הסוד. דף נקודת הקצה מציג רק את התווים הראשונים שלו.
האם לכל נקודות הקצה שלי יש סוד אחד?
לא. לכל נקודת קצה יש סוד חתימה משלה, לכן יש לבדוק כל בקשה עם הסוד של נקודת הקצה שאליה היא נשלחה.