Xác minh rằng webhook đến từ Notiondesk

Kiểm tra tiêu đề X-ND-Signature trên các yêu cầu webhook Notiondesk với khóa bí mật ký của bạn, với các ví dụ đã được kiểm thử bằng Node.js và Python.

8 phút đọc

Mỗi yêu cầu webhook đều được ký bằng khóa bí mật ký của điểm cuối của bạn. Hãy kiểm tra chữ ký trước khi tin tưởng một yêu cầu, để máy chủ của bạn chỉ xử lý các sự kiện thực sự đến từ Notiondesk và không bị thay đổi trên đường truyền.

Cách nhanh: Đọc và từ phần tiêu đề, tính toán mã SHA-256 HMAC bằng khóa bí mật ký của bạn, so sánh nó với và từ chối các yêu cầu cũ hơn 5 phút.tv1X-ND-Signature{t}.{raw body}v1

Trước khi bạn bắt đầu

  • Bạn có mã bí mật ký mà bạn đã sao chép khi thêm điểm cuối. Mã này bắt đầu bằng nd_whsec_. Nếu bạn làm mất nó, hãy xoay vòng mã bí mật. Xem phần Xoay vòng mã bí mật ký .
  • Bộ thu của bạn có thể đọc nội dung yêu cầu chính xác như khi nó được gửi đến, trước khi bất kỳ quá trình phân tích cú pháp JSON nào diễn ra.

Cách thức hoạt động của chữ ký

Mỗi yêu cầu đều có tiêu đề X-ND-Signature:

X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb
Phần Nó là gì?
tThời điểm yêu cầu được gửi, tính bằng giây kể từ ngày 1 tháng 1 năm 1970 (UTC). Mỗi lần thử lại sẽ nhận được một giá trị t mới.
v1Mã SHA-256 của HMAC của t, dấu chấm và phần thân yêu cầu thô, được ký bằng khóa bí mật ký của bạn và được viết dưới dạng chữ thập lục phân thường.

Xác minh yêu cầu

  1. Đọc toàn bộ nội dung yêu cầu thô dưới dạng byte. Không cần phân tích cú pháp trước.
  1. Tách phần tiêu đề X-ND-Signature theo dấu phẩy và đọc t và v1.
  1. Xây dựng văn bản đã ký: t, dấu chấm, sau đó là nội dung thô. Ví dụ: 1794955939.{"id":"019a8f2e-...",...}.
  1. Tính toán mã SHA-256 HMAC của văn bản đó với toàn bộ khóa bí mật ký của bạn, bao gồm cả nd_whsec_, và viết nó dưới dạng chữ thập lục phân thường.
  1. So sánh kết quả của bạn với v1 bằng cách sử dụng phép so sánh trong thời gian không đổi.
  1. Hãy kiểm tra xem t có nằm trong vòng 5 phút so với thời gian của máy chủ của bạn hay không.
  1. Nếu bất kỳ kiểm tra nào thất bại, hãy trả lời 400 và bỏ qua yêu cầu. Nếu tất cả đều thành công, hãy trả lời 200 và xử lý sự kiện.

Ví dụ về Node.js

Chức năng này hoạt động với Node.js 18 trở lên và Express. express.raw giữ nguyên phần thân dưới dạng byte thô, điều mà chữ ký yêu cầu.

Ví dụ Python

Chức năng này hoạt động với Python 3.9 trở lên và Flask. request.get_data() trả về nội dung thô.

Xoay bí mật ký kết

Hãy thay đổi bí mật nếu nó có thể bị rò rỉ hoặc nếu bạn đã làm mất nó.

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. Mở điểm cuối trong Cài đặt > Nhà phát triển > Webhooks .
  1. Trong phần "Bí mật ký tên" , hãy nhấp vào "Xoay" , sau đó nhấp vào "Xoay" một lần nữa để xác nhận.
  1. Sao chép mã bí mật mới, lưu trữ nó trên máy chủ của bạn, sau đó nhấp vào "Tôi đã lưu" .
Mã bí mật cũ sẽ ngừng hoạt động ngay lập tức. Mọi yêu cầu được gửi sau khi xoay vòng, bao gồm cả việc thử lại các sự kiện trước đó, đều được ký bằng mã bí mật mới, vì vậy hãy cập nhật máy chủ của bạn cùng lúc.

Nếu một vài yêu cầu thất bại trong quá trình chuyển đổi, chúng sẽ được thử lại sau 1 phút với mã bí mật mới.

Những lỗi thường gặp

  • Kiểm tra JSON đã được phân tích cú pháp thay vì toàn bộ nội dung thô. Việc phân tích nội dung và chuyển đổi lại thành văn bản sẽ làm thay đổi khoảng cách và ký tự thoát, do đó chữ ký không còn khớp nữa. Hãy xác minh các byte bạn nhận được, sau đó mới phân tích cú pháp.
  • Sử dụng sai mã bí mật. Mỗi điểm cuối có mã bí mật riêng. Hãy sử dụng toàn bộ giá trị, bao gồm cả nd_whsec_, và giá trị mới nhất nếu bạn đã xoay vòng nó.
  • Đồng hồ máy chủ bị sai lệch. Nếu đồng hồ máy chủ của bạn bị lệch quá vài phút, các yêu cầu hợp lệ sẽ hiển thị quá cũ. Hãy giữ cho đồng hồ luôn đồng bộ, ví dụ như với NTP.
  • So sánh bằng phép kiểm tra đẳng thức thông thường. Sử dụng phép so sánh có thời gian thực hiện không đổi, ví dụ như crypto.timingSafeEqual trong Node.js hoặc hmac.compare_digest trong Python.

Câu hỏi thường gặp

Tại sao lại từ chối các yêu cầu cũ hơn 5 phút?

Một yêu cầu đã được bắt giữ có thể được gửi lại máy chủ của bạn sau đó. Việc kiểm tra t giới hạn điều đó trong một khoảng thời gian ngắn. Mỗi lần thử lại được ký lại bằng một t mới, vì vậy các lần thử lại vẫn thành công.

Sự kiện kiểm thử đã được ký chưa?

Vâng. Nhấp vào "Gửi sự kiện kiểm thử" trên trang điểm cuối để kiểm tra mã xác minh của bạn. Nếu mã hiển thị là 200 trong mục "Các lần giao hàng gần đây" thì có nghĩa là quá trình đã thành công.

Tôi có thể xem lại bí quyết ký kết được không?

Không. Nó chỉ hiển thị một lần, khi bạn thêm điểm cuối hoặc xoay vòng khóa bí mật. Trang điểm cuối chỉ hiển thị các ký tự đầu tiên của nó.

Tất cả các điểm cuối của tôi có dùng chung một khóa bí mật không?

Không. Mỗi điểm cuối (endpoint) có một mã bí mật ký riêng, vì vậy hãy kiểm tra từng yêu cầu với mã bí mật của điểm cuối mà nó được gửi đến.

Bài viết liên quan

Trang này có hữu ích không?

Still need help? Ask us