Sprawdź, czy webhook pochodzi z Notiondesk

Sprawdź nagłówek X-ND-Signature w żądaniach webhooka Notiondesk przy użyciu swojego klucza podpisu, korzystając z przetestowanych przykładów Node.js i Pythona.

5 min czytania

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.

Szybka ścieżka: Odczytaj i z nagłówka oblicz algorytm HMAC SHA-256 przy użyciu swojego tajnego klucza podpisu, porównaj go z żądaniami starszymi niż 5 minut i odrzuć je.tv1X-ND-Signature{t}.{raw body}v1

Zanim 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
tData wysłania żądania (w sekundach) od 1 stycznia 1970 r. (UTC). Każda ponowna próba otrzymuje nowy t
v1HMAC SHA-256 t, kropka i surowe ciało żądania podpisane Twoim tajnym kluczem podpisu i zapisane małymi literami w kodzie szesnastkowym

Zweryfikuj żądanie

  1. Przeczytaj surowe ciało żądania jako bajty. Nie analizuj go najpierw.
  1. Podziel nagłówek X-ND-Signature na przecinki i odczytaj t i v1.
  1. Zbuduj podpisany tekst: t, kropkę, a następnie surowe ciało. Na przykład 1794955939.{"id":"019a8f2e-...",...}.
  1. 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.
  1. Porównaj swój wynik z v1, używając porównania w czasie stałym.
  1. Sprawdź, czy t różni się w zależności od czasu serwera o maksymalnie 5 minut.
  1. Jeśli którekolwiek sprawdzenie się nie powiedzie, odpowiedz na 400 i zignoruj ​​żądanie. Jeśli wszystkie testy zakończą się powodzeniem, odpowiedz na 200 i 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
  1. Otwórz punkt końcowy w Ustawienia > Deweloperzy > Webhooki .
  1. W obszarze Podpisywanie tajne kliknij opcję Obróć , a następnie ponownie Obróć, aby potwierdzić.
  1. Skopiuj nowy sekret, zapisz go na serwerze, a następnie kliknij przycisk Zapisałem .
Stary sekret przestaje działać natychmiast. Każde żądanie wysłane po rotacji, w tym powtórzenia wcześniejszych zdarzeń, jest podpisywane nowym sekretem, dlatego należy jednocześnie zaktualizować serwer.

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.timingSafeEqual w Node.js lub hmac.compare_digest w 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.

Powiązane artykuły

Czy ta strona była pomocna?

Still need help? Ask us