ודא ש-webhook מגיע מ-Notiondesk

בדוק את כותרת ה-X-ND-Signature בבקשות webhook Notiondesk עם סוד החתימה שלך, עם דוגמאות שנבדקו עבור Node.js ו-Python.

2 דקות קריאה

כל בקשת webhook נחתמת עם סוד החתימה של נקודת הקצה שלך. בדוק את החתימה לפני שאתה נותן אמון בבקשה, כך שהשרת שלך יפעל רק על אירועים שמגיעים באמת מ-Notiondesk ולא שונו בדרך.

נתיב מהיר: קרא ומהכותרת, חשב HMAC SHA-256 עם סוד החתימה שלך, השווה אותו לבקשות בנות יותר מ-5 דקות ודחה אותן.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, נקודה וגוף הבקשה הגולמי, חתום עם סוד החתימה שלך וכתוב כקובץ הקסדצימלי קטן

אימות בקשה

  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 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. העתיקו את הסוד החדש, אחסן אותו בשרת שלכם ולאחר מכן לחצו על שמרתי אותו .
הסוד הישן מפסיק לפעול באופן מיידי. כל בקשה שנשלחת לאחר הרוטציה, כולל ניסיונות חוזרים של אירועים קודמים, נחתמת עם הסוד החדש, לכן עדכן את השרת שלך בו זמנית.

אם מספר בקשות נכשלות בזמן המעבר, הן יתבצעו שוב לאחר דקה עם הסוד החדש.

טעויות נפוצות

  • בדיקת JSON מנותח במקום גוף הקובץ הגולמי. ניתוח הגוף והפיכתו חזרה לטקסט משנה את המרווח ואת תווי ה-escape, כך שהחתימה כבר לא תואמת. ודאו את הבייטים שקיבלת, ולאחר מכן נתחו.
  • שימוש בסוד שגוי. לכל נקודת קצה יש סוד משלה. השתמש בערך המלא, כולל nd_whsec_, ובערך העדכני ביותר אם סובבת אותו.
  • שעון שרת שגוי. אם שעון השרת שלך שגוי ביותר מכמה דקות, בקשות תקפות נראות ישנות מדי. שמור על סנכרון השעון, לדוגמה עם NTP.
  • השוואה עם בדיקת שוויון פשוטה. השתמשו בהשוואה בזמן קבוע, כמו crypto.timingSafeEqual ב-Node.js או hmac.compare_digest בפייתון.

שאלות נפוצות

למה לדחות בקשות בנות יותר מ-5 דקות?

בקשה שנלכדה עלולה להישלח שוב לשרת שלך מאוחר יותר. בדיקת t מגבילה זאת לחלון זמן קצר. כל ניסיון חוזר נחתם שוב עם t חדש, כך שניסיונות חוזרים עדיין יעברו.

האם אירוע הבדיקה חתום?

כן. לחץ על שלח אירוע בדיקה בדף נקודת הקצה כדי לבדוק את קוד האימות שלך. 200 תחת משלוחים אחרונים פירושו שההזמנה עברה.

האם אוכל לראות שוב את סוד החתימה?

לא. הוא מוצג פעם אחת, כאשר מוסיפים את נקודת הקצה או מסובבים את הסוד. דף נקודת הקצה מציג רק את התווים הראשונים שלו.

האם לכל נקודות הקצה שלי יש סוד אחד?

לא. לכל נקודת קצה יש סוד חתימה משלה, לכן יש לבדוק כל בקשה עם הסוד של נקודת הקצה שאליה היא נשלחה.

מאמרים קשורים

האם הדף הזה היה מועיל?

Still need help? Ask us