Jede Webhook-Anfrage wird mit dem Signaturschlüssel Ihres Endpunkts signiert. Überprüfen Sie die Signatur, bevor Sie einer Anfrage vertrauen, damit Ihr Server nur auf Ereignisse reagiert, die tatsächlich von Notiondesk stammen und auf dem Weg nicht verändert wurden.
tv1X-ND-Signature{t}.{raw body}v1Bevor Sie beginnen
- Sie besitzen das Signaturgeheimnis, das Sie beim Hinzufügen des Endpunkts kopiert haben. Es beginnt mit
nd_whsec_. Falls Sie es verloren haben, rotieren Sie es. Siehe „Signaturgeheimnis rotieren“ .
- Ihr Empfänger kann den Anfragetext genau so lesen, wie er angekommen ist, bevor er in JSON umgewandelt wird.
So funktioniert die Signatur
Jede Anfrage hat einen X-ND-Signature-Header:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Teil | Was es ist |
|---|---|
t | Die Anfrage wurde in Sekunden seit dem 1. Januar 1970 (UTC) gesendet. Jeder Wiederholungsversuch erhält eine neue t-Zahl. |
v1 | Der HMAC-SHA-256-Hash von t, einem Punkt und dem Rohdatensatz der Anfrage, signiert mit Ihrem Signaturgeheimnis und als Kleinbuchstaben-Hexadezimalzahl geschrieben. |
Eine Anfrage überprüfen
- Lesen Sie den unformatierten Anfragetext als Bytes. Parsen Sie ihn nicht vorher.
- Teile den
X-ND-Signature-Header an den Kommas auf und liestundv1.
- Erstellen Sie den signierten Text:
t, ein Punkt, dann der Rohtext. Zum Beispiel1794955939.{"id":"019a8f2e-...",...}.
- Berechnen Sie einen HMAC SHA-256-Hash dieses Textes mit Ihrem vollständigen Signaturgeheimnis, einschließlich
nd_whsec_, und schreiben Sie ihn als Kleinbuchstaben-Hexadezimalzahl.
- Vergleichen Sie Ihr Ergebnis mit
v1mithilfe eines Vergleichs mit konstanter Laufzeit.
- Prüfen Sie, ob
tinnerhalb von 5 Minuten der Serverzeit liegt.
- Schlägt eine Prüfung fehl, antworten Sie mit
400und ignorieren Sie die Anfrage. Sind alle Prüfungen erfolgreich, antworten Sie mit200und behandeln Sie das Ereignis.
Node.js-Beispiel
Dies funktioniert mit Node.js 18 oder höher und Express. express.raw speichert den Body als Rohbytes, was für die Signatur erforderlich ist.
Python-Beispiel
Dies funktioniert mit Python 3.9 oder höher und Flask. request.get_data() gibt den Rohdatenkörper zurück.
Drehen Sie das Signaturgeheimnis
Drehen Sie das Geheimnis um, falls es durchgesickert sein sollte oder falls Sie es verloren haben.
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- Öffnen Sie den Endpunkt unter Einstellungen > Entwickler > Webhooks .
- Klicken Sie unter „Signaturgeheimnis“ auf „Drehen“ und dann zur Bestätigung erneut auf „Drehen“ .
- Kopiere das neue Geheimnis, speichere es auf deinem Server und klicke dann auf „Ich habe es gespeichert“ .
Falls während des Wechsels einige Anfragen fehlschlagen, werden sie nach 1 Minute mit dem neuen Geheimnis erneut versucht.
Häufige Fehler
- Prüfen Sie das geparste JSON anstelle des Rohdatenkörpers. Durch das Parsen des Datenkörpers und die Rückkonvertierung in Text ändern sich Leerzeichen und Escape-Sequenzen, sodass die Signatur nicht mehr übereinstimmt. Überprüfen Sie die empfangenen Bytes, bevor Sie sie parsen.
- Falsches Geheimnis verwendet. Jeder Endpunkt hat sein eigenes Geheimnis. Verwenden Sie den gesamten Wert, einschließlich
nd_whsec_, und gegebenenfalls den neuesten Wert, falls Sie ihn geändert haben.
- Die Serveruhr ist falsch. Weicht die Uhrzeit Ihres Servers um mehr als ein paar Minuten ab, erscheinen gültige Anfragen zu alt. Synchronisieren Sie die Uhrzeit, beispielsweise mit NTP.
- Vergleichen Sie nicht mit einem einfachen Gleichheitstest. Verwenden Sie einen Vergleich mit konstanter Laufzeit, wie z. B.
crypto.timingSafeEqualin Node.js oderhmac.compare_digestin Python.
Häufig gestellte Fragen
Warum werden Anfragen abgelehnt, die älter als 5 Minuten sind?
Eine abgefangene Anfrage kann später erneut an Ihren Server gesendet werden. Die Prüfung von t begrenzt dies auf ein kurzes Zeitfenster. Jeder Wiederholungsversuch wird erneut mit einem neuen t signiert, sodass Wiederholungsversuche weiterhin erfolgreich sind.
Ist das Testereignis signiert?
Ja. Klicken Sie auf der Endpunktseite auf „Testereignis senden“ , um Ihren Bestätigungscode zu überprüfen. Ein Eintrag „200“ unter „Letzte Lieferungen“ bedeutet, dass die Prüfung erfolgreich war.
Kann ich das Signaturgeheimnis noch einmal sehen?
Nein. Es wird nur einmal angezeigt, wenn Sie den Endpunkt hinzufügen oder das Geheimnis ändern. Auf der Endpunktseite werden nur die ersten Zeichen angezeigt.
Haben alle meine Endpunkte ein gemeinsames Geheimnis?
Nein. Jeder Endpunkt hat sein eigenes Signaturgeheimnis. Überprüfen Sie daher jede Anfrage mit dem Geheimnis des Endpunkts, an den sie gesendet wurde.