Controleer of een webhook afkomstig is van Notiondesk

Controleer de X-ND-Signature-header op Notiondesk-webhookverzoeken met uw ondertekeningsgeheim, met geteste Node.js- en Python-voorbeelden.

4 min lezen

Elke webhook-aanvraag wordt ondertekend met het ondertekeningsgeheim van uw eindpunt. Controleer de handtekening voordat u een aanvraag vertrouwt, zodat uw server alleen reageert op gebeurtenissen die daadwerkelijk afkomstig zijn van Notiondesk en onderweg niet zijn gewijzigd.

Snelle methode: Lees de header, bereken een HMAC SHA-256-hash met uw ondertekeningsgeheim, vergelijk deze met de header en weiger verzoeken die ouder zijn dan 5 minuten.tv1X-ND-Signature{t}.{raw body}v1

Voordat je begint

  • Je hebt het ondertekeningsgeheim dat je hebt gekopieerd toen je het eindpunt toevoegde. Het begint met nd_whsec_. Als je het kwijt bent, roteer het dan. Zie Het ondertekeningsgeheim roteren .
  • Uw ontvanger kan de aanvraagbody exact lezen zoals deze is binnengekomen, vóórdat er JSON-parsing heeft plaatsgevonden.

Hoe de handtekening werkt

Elk verzoek heeft een X-ND-Signature-header:

X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb
Deel Wat het is
tHet tijdstip waarop het verzoek werd verzonden, in seconden sinds 1 januari 1970 (UTC). Elke nieuwe poging krijgt een nieuwe t.
v1De HMAC SHA-256 van t, een punt en de onbewerkte aanvraagbody, ondertekend met uw ondertekeningsgeheim en geschreven in kleine hexadecimale letters.

Een verzoek verifiëren

  1. Lees de onbewerkte request body als bytes. Parseer deze niet eerst.
  1. Splits de koptekst X-ND-Signature op komma's en lees t en v1.
  1. Stel de ondertekende tekst samen: t, een punt, en vervolgens de onbewerkte tekst. Bijvoorbeeld 1794955939.{"id":"019a8f2e-...",...}.
  1. Bereken een HMAC SHA-256-hash van die tekst met uw volledige ondertekeningsgeheim, inclusief nd_whsec_, en schrijf deze als kleine hexadecimale notatie.
  1. Vergelijk uw resultaat met v1 met behulp van een vergelijking met constante tijd.
  1. Controleer of t binnen 5 minuten van de tijd van uw server ligt.
  1. Als een van de controles mislukt, antwoord dan 400 en negeer het verzoek. Als alle controles slagen, antwoord dan 200 en verwerk de gebeurtenis.

Node.js-voorbeeld

Dit werkt met Node.js 18 of later en Express. express.raw houdt de body als onbewerkte bytes, wat de handtekening vereist.

Python-voorbeeld

Dit werkt met Python 3.9 of later en Flask. request.get_data() retourneert de onbewerkte body.

Draai het ondertekeningsgeheim om

Vernieuw het geheim als het mogelijk is uitgelekt, of als je het kwijt bent.

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. Open het eindpunt in Instellingen > Ontwikkelaars > Webhooks .
  1. Klik onder 'Ondertekeningsgeheim' op 'Draaien' en vervolgens nogmaals op 'Draaien' om te bevestigen.
  1. Kopieer het nieuwe geheim, sla het op je server op en klik vervolgens op 'Ik heb het opgeslagen' .
Het oude geheim werkt direct niet meer. Elk verzoek dat na de rotatie wordt verzonden, inclusief herhalingen van eerdere gebeurtenissen, wordt ondertekend met het nieuwe geheim. Werk uw server daarom tegelijkertijd bij.

Als er tijdens het overschakelen een paar verzoeken mislukken, worden deze na 1 minuut opnieuw geprobeerd met het nieuwe geheim.

Veelgemaakte fouten

  • Controleer de geparseerde JSON in plaats van de onbewerkte body. Het parsen van de body en het terugzetten naar tekst verandert de spaties en escapetekens, waardoor de handtekening niet meer overeenkomt. Controleer de ontvangen bytes en parseer ze vervolgens.
  • Het verkeerde geheim gebruiken. Elk eindpunt heeft zijn eigen geheim. Gebruik de volledige waarde, inclusief nd_whsec_, en de meest recente waarde als je deze hebt gewijzigd.
  • Een verkeerde serverklok. Als de klok van uw server meer dan een paar minuten afwijkt, lijken geldige verzoeken te oud. Zorg ervoor dat de klok gesynchroniseerd blijft, bijvoorbeeld met NTP.
  • Vergelijken met een eenvoudige gelijkheidscontrole. Gebruik een vergelijking met constante tijd, zoals crypto.timingSafeEqual in Node.js of hmac.compare_digest in Python.

Veelgestelde vragen

Waarom worden verzoeken ouder dan 5 minuten afgewezen?

Een onderschept verzoek kan later opnieuw naar uw server worden verzonden. Door t te controleren, wordt dit beperkt tot een kort tijdsvenster. Elke herhaalpoging wordt opnieuw ondertekend met een nieuwe t, waardoor herhaalpogingen nog steeds slagen.

Is de testgebeurtenis ondertekend?

Ja. Klik op 'Testgebeurtenis verzenden' op de eindpuntpagina om uw verificatiecode te controleren. Een 200 onder 'Recente leveringen' betekent dat de verificatie geslaagd is.

Mag ik het geheim van de handtekening nog eens zien?

Nee. Het wordt slechts één keer weergegeven, wanneer je het eindpunt toevoegt of het geheim wijzigt. Op de eindpuntpagina worden alleen de eerste tekens weergegeven.

Delen al mijn eindpunten één geheim?

Nee. Elk eindpunt heeft zijn eigen ondertekeningsgeheim, dus controleer elk verzoek met het geheim van het eindpunt waarnaar het is verzonden.

Gerelateerde artikelen

Was deze pagina nuttig?

Still need help? Ask us