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.
tv1X-ND-Signature{t}.{raw body}v1Voordat 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 |
|---|---|
t | Het tijdstip waarop het verzoek werd verzonden, in seconden sinds 1 januari 1970 (UTC). Elke nieuwe poging krijgt een nieuwe t. |
v1 | De 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
- Lees de onbewerkte request body als bytes. Parseer deze niet eerst.
- Splits de koptekst
X-ND-Signatureop komma's en leestenv1.
- Stel de ondertekende tekst samen:
t, een punt, en vervolgens de onbewerkte tekst. Bijvoorbeeld1794955939.{"id":"019a8f2e-...",...}.
- Bereken een HMAC SHA-256-hash van die tekst met uw volledige ondertekeningsgeheim, inclusief
nd_whsec_, en schrijf deze als kleine hexadecimale notatie.
- Vergelijk uw resultaat met
v1met behulp van een vergelijking met constante tijd.
- Controleer of
tbinnen 5 minuten van de tijd van uw server ligt.
- Als een van de controles mislukt, antwoord dan
400en negeer het verzoek. Als alle controles slagen, antwoord dan200en 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- Open het eindpunt in Instellingen > Ontwikkelaars > Webhooks .
- Klik onder 'Ondertekeningsgeheim' op 'Draaien' en vervolgens nogmaals op 'Draaien' om te bevestigen.
- Kopieer het nieuwe geheim, sla het op je server op en klik vervolgens op 'Ik heb het opgeslagen' .
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.timingSafeEqualin Node.js ofhmac.compare_digestin 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.