Überprüfen Sie, ob ein Webhook von Notiondesk stammt.

Prüfen Sie den X-ND-Signature-Header bei Notiondesk-Webhook-Anfragen mit Ihrem Signaturgeheimnis. Es gibt getestete Beispiele für Node.js und Python.

5 Min. Lesezeit

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.

Kurzanleitung: Lesen Sie den Header, berechnen Sie einen HMAC SHA-256-Hash mit Ihrem Signaturgeheimnis, vergleichen Sie ihn mit dem Referenzwert und weisen Sie Anfragen zurück, die älter als 5 Minuten sind.tv1X-ND-Signature{t}.{raw body}v1

Bevor 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
tDie Anfrage wurde in Sekunden seit dem 1. Januar 1970 (UTC) gesendet. Jeder Wiederholungsversuch erhält eine neue t-Zahl.
v1Der 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

  1. Lesen Sie den unformatierten Anfragetext als Bytes. Parsen Sie ihn nicht vorher.
  1. Teile den X-ND-Signature-Header an den Kommas auf und lies t und v1.
  1. Erstellen Sie den signierten Text: t, ein Punkt, dann der Rohtext. Zum Beispiel 1794955939.{"id":"019a8f2e-...",...}.
  1. 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.
  1. Vergleichen Sie Ihr Ergebnis mit v1 mithilfe eines Vergleichs mit konstanter Laufzeit.
  1. Prüfen Sie, ob t innerhalb von 5 Minuten der Serverzeit liegt.
  1. Schlägt eine Prüfung fehl, antworten Sie mit 400 und ignorieren Sie die Anfrage. Sind alle Prüfungen erfolgreich, antworten Sie mit 200 und 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
  1. Öffnen Sie den Endpunkt unter Einstellungen > Entwickler > Webhooks .
  1. Klicken Sie unter „Signaturgeheimnis“ auf „Drehen“ und dann zur Bestätigung erneut auf „Drehen“ .
  1. Kopiere das neue Geheimnis, speichere es auf deinem Server und klicke dann auf „Ich habe es gespeichert“ .
Das alte Geheimnis ist sofort nicht mehr gültig. Jede Anfrage, die nach der Rotation gesendet wird, einschließlich Wiederholungsversuchen früherer Ereignisse, wird mit dem neuen Geheimnis signiert. Aktualisieren Sie daher gleichzeitig Ihren Server.

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.timingSafeEqual in Node.js oder hmac.compare_digest in 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.

Verwandte Artikel

War diese Seite hilfreich?

Still need help? Ask us