Każde żądanie webhooka jest podpisywane tajnym kluczem podpisu Twojego punktu końcowego. Sprawdź podpis przed zaufaniem żądaniu, aby serwer reagował tylko na zdarzenia, które faktycznie pochodzą z Notiondesk i nie zostały zmienione po drodze.
tv1X-ND-Signature{t}.{raw body}v1Zanim zaczniesz
- Masz tajny klucz podpisu, który skopiowałeś podczas dodawania punktu końcowego. Zaczyna się on od
nd_whsec_. Jeśli go zgubiłeś, zmień go. Zobacz Rotacja tajnego klucza podpisu .
- Odbiorca może odczytać treść żądania w dokładnie takiej formie, w jakiej zostało otrzymane, przed jakimkolwiek przetwarzaniem JSON.
Jak działa podpis
Każde żądanie ma nagłówek X-ND-Signature:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Część | Co to jest |
|---|---|
t | Data wysłania żądania (w sekundach) od 1 stycznia 1970 r. (UTC). Każda ponowna próba otrzymuje nowy t |
v1 | HMAC SHA-256 t, kropka i surowe ciało żądania podpisane Twoim tajnym kluczem podpisu i zapisane małymi literami w kodzie szesnastkowym |
Zweryfikuj żądanie
- Przeczytaj surowe ciało żądania jako bajty. Nie analizuj go najpierw.
- Podziel nagłówek
X-ND-Signaturena przecinki i odczytajtiv1.
- Zbuduj podpisany tekst:
t, kropkę, a następnie surowe ciało. Na przykład1794955939.{"id":"019a8f2e-...",...}.
- Oblicz algorytm HMAC SHA-256 tego tekstu, uwzględniając pełny klucz podpisu, wliczając
nd_whsec_, i zapisz go jako małe litery w kodzie szesnastkowym.
- Porównaj swój wynik z
v1, używając porównania w czasie stałym.
- Sprawdź, czy
tróżni się w zależności od czasu serwera o maksymalnie 5 minut.
- Jeśli którekolwiek sprawdzenie się nie powiedzie, odpowiedz na
400i zignoruj żądanie. Jeśli wszystkie testy zakończą się powodzeniem, odpowiedz na200i obsłuż zdarzenie.
Przykład Node.js
Działa z Node.js 18 i nowszymi wersjami oraz Express. express.raw zachowuje treść jako surowe bajty, których potrzebuje podpis.
Przykład Pythona
Działa z Pythonem 3.9 i nowszymi wersjami oraz Flaskiem. request.get_data() zwraca surowe ciało.
Obróć klucz podpisu
Obróć sekret, jeśli wyciekł lub go zgubiłeś.
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- Otwórz punkt końcowy w Ustawienia > Deweloperzy > Webhooki .
- W obszarze Podpisywanie tajne kliknij opcję Obróć , a następnie ponownie Obróć, aby potwierdzić.
- Skopiuj nowy sekret, zapisz go na serwerze, a następnie kliknij przycisk Zapisałem .
Jeśli podczas przełączania kilka żądań się nie powiedzie, zostaną one ponowione po 1 minucie z użyciem nowego klucza tajnego.
Typowe błędy
- Sprawdzanie sparsowanego JSON-a zamiast surowego ciała. Parsowanie ciała i zamiana go z powrotem na tekst zmienia odstępy i znaki ucieczki, przez co podpis przestaje się zgadzać. Sprawdź otrzymane bajty, a następnie sparsuj.
- Użycie nieprawidłowego klucza tajnego. Każdy punkt końcowy ma swój własny klucz tajny. Użyj całej wartości, łącznie z
nd_whsec_, a także najnowszej, jeśli została obrócona.
- Nieprawidłowy zegar serwera. Jeśli zegar serwera spóźnia się o więcej niż kilka minut, prawidłowe żądania wyglądają na zbyt stare. Synchronizuj zegar, na przykład z protokołem NTP.
- Porównywanie z prostym sprawdzaniem równości. Użyj porównania w czasie stałym, takiego jak
crypto.timingSafeEqualw Node.js lubhmac.compare_digestw Pythonie.
Często zadawane pytania
Dlaczego odrzucać prośby starsze niż 5 minut?
Przechwycone żądanie może zostać ponownie wysłane do serwera później. Sprawdzenie t ogranicza to do krótkiego okna. Każda ponowna próba jest ponownie podpisywana nowym t, więc ponowne próby nadal są zaliczane.
Czy zdarzenie testowe jest podpisane?
Tak. Kliknij „Wyślij zdarzenie testowe” na stronie punktu końcowego, aby sprawdzić kod weryfikacyjny. Wartość 200 w sekcji „Ostatnie dostawy” oznacza, że zdarzenie zostało pomyślnie dostarczone.
Czy mogę jeszcze raz zobaczyć tajny kod podpisu?
Nie. Jest wyświetlany tylko raz, po dodaniu punktu końcowego lub obróceniu klucza tajnego. Strona punktu końcowego wyświetla tylko jego pierwsze znaki.
Czy wszystkie moje punkty końcowe współdzielą jeden sekret?
Nie. Każdy punkt końcowy ma swój własny tajny podpis, dlatego sprawdzaj każde żądanie pod kątem tajnego podpisu punktu końcowego, do którego zostało wysłane.