Meldungen
Signatur prüfen
Jede Kursmeldung ist mit dem Geheimnis des Endpunkts signiert. Die Gegenstelle rechnet die Signatur nach und nimmt nur an, was stimmt. Ohne diese Prüfung könnte jeder, der die Adresse kennt, Kurse eintragen.
X-Skirent-Signature: t=1794680608,v1=5f2c…| Teil | Bedeutung |
|---|---|
t |
Zeitpunkt des Sendens in Unix-Sekunden |
v1 |
HMAC-SHA256 als Hexadezimalzahl |
Signiert wird die Zeichenkette aus t, einem Punkt und dem Rumpf der Anfrage, mit dem Geheimnis als Schlüssel:
v1 = HMAC-SHA256(geheimnis, t + "." + rumpf)Prüfschritte
Abschnitt betitelt „Prüfschritte“- Den Rumpf roh lesen, Byte für Byte, bevor ein JSON-Parser ihn anfasst. Ein neu geschriebenes JSON hat andere Leerzeichen oder eine andere Reihenfolge, und die Signatur passt nicht mehr.
tundv1aus dem Kopf lesen.- Nachrechnen und vergleichen, mit einem Vergleich in konstanter Zeit.
- Das Alter prüfen. Lehnen Sie ab, was älter als fünf Minuten ist. Das schützt davor, dass jemand eine mitgeschnittene Meldung später noch einmal einspielt.
Erst danach wird der Rumpf gelesen und verarbeitet.
Codebeispiele
Abschnitt betitelt „Codebeispiele“import { createHmac, timingSafeEqual } from 'node:crypto';import { createServer } from 'node:http';
const SECRET = process.env.SKI4ME_WEBHOOK_SECRET; // whsec_…const MAX_ALTER_S = 300;
function gueltig(kopf, rumpf) { const teile = Object.fromEntries(String(kopf ?? '').split(',').map((t) => t.split('='))); const zeit = Number(teile.t); if (!zeit || !teile.v1) return false; if (Math.abs(Date.now() / 1000 - zeit) > MAX_ALTER_S) return false;
const erwartet = createHmac('sha256', SECRET).update(`${zeit}.${rumpf}`).digest(); const bekommen = Buffer.from(teile.v1, 'hex'); return bekommen.length === erwartet.length && timingSafeEqual(bekommen, erwartet);}
const gesehen = new Set(); // im Betrieb: eine Tabelle mit eindeutigem Schlüssel
createServer((req, res) => { const stuecke = []; req.on('data', (s) => stuecke.push(s)); req.on('end', () => { const rumpf = Buffer.concat(stuecke).toString('utf8'); // roh, nicht neu geschrieben
if (!gueltig(req.headers['x-skirent-signature'], rumpf)) { res.writeHead(401).end(); return; }
const zustellung = req.headers['x-skirent-delivery']; if (!gesehen.has(zustellung)) { gesehen.add(zustellung); const meldung = JSON.parse(rumpf); if (!meldung.test) verarbeite(meldung.event, meldung.course); } res.writeHead(204).end(); // schnell antworten, auch bei einer Doppelten });}).listen(8080);
function verarbeite(ereignis, kurs) { console.log(ereignis, kurs.uid, kurs.status, kurs.courseName, kurs.date);}import hashlibimport hmacimport jsonimport osimport time
from flask import Flask, request
SECRET = os.environ["SKI4ME_WEBHOOK_SECRET"].encode() # whsec_…MAX_ALTER_S = 300
app = Flask(__name__)gesehen = set() # im Betrieb: eine Tabelle mit eindeutigem Schlüssel
def gueltig(kopf: str, rumpf: bytes) -> bool: teile = dict(t.split("=", 1) for t in (kopf or "").split(",") if "=" in t) try: zeit = int(teile["t"]) bekommen = teile["v1"] except (KeyError, ValueError): return False if abs(time.time() - zeit) > MAX_ALTER_S: return False erwartet = hmac.new(SECRET, f"{zeit}.".encode() + rumpf, hashlib.sha256).hexdigest() return hmac.compare_digest(erwartet, bekommen)
@app.post("/hooks/ski4me")def meldung(): rumpf = request.get_data() # roh, nicht request.json if not gueltig(request.headers.get("X-Skirent-Signature"), rumpf): return "", 401
zustellung = request.headers["X-Skirent-Delivery"] if zustellung not in gesehen: gesehen.add(zustellung) daten = json.loads(rumpf) if not daten.get("test"): verarbeite(daten["event"], daten["course"]) return "", 204 # schnell antworten, auch bei einer Doppelten
def verarbeite(ereignis: str, kurs: dict) -> None: print(ereignis, kurs["uid"], kurs["status"], kurs["courseName"], kurs["date"])<?php
const MAX_ALTER_S = 300;
$secret = getenv('SKI4ME_WEBHOOK_SECRET'); // whsec_…$rumpf = file_get_contents('php://input'); // roh, nicht neu geschrieben$kopf = $_SERVER['HTTP_X_SKIRENT_SIGNATURE'] ?? '';
$teile = [];foreach (explode(',', $kopf) as $teil) { [$name, $wert] = array_pad(explode('=', $teil, 2), 2, ''); $teile[$name] = $wert;}
$zeit = (int) ($teile['t'] ?? 0);$erwartet = hash_hmac('sha256', $zeit . '.' . $rumpf, $secret);
if ( $zeit === 0 || abs(time() - $zeit) > MAX_ALTER_S || !hash_equals($erwartet, $teile['v1'] ?? '')) { http_response_code(401); exit;}
$zustellung = $_SERVER['HTTP_X_SKIRENT_DELIVERY'];$meldung = json_decode($rumpf, true);
// schonGesehen() und merke(): eine Tabelle mit eindeutigem Schlüssel auf der Kennung.if (!schonGesehen($zustellung)) { merke($zustellung); if (empty($meldung['test'])) { verarbeite($meldung['event'], $meldung['course']); }}
http_response_code(204); // schnell antworten, auch bei einer DoppeltenTestvektor
Abschnitt betitelt „Testvektor“Mit diesen Werten lässt sich eine eigene Prüfung testen, bevor die erste echte Meldung kommt. Sie stammen aus der Testmeldung des Mitschnitts; das Geheimnis gehört zu einer Ablage, die es nicht mehr gibt.
- Geheimnis
- whsec_gEUdLhouThmd-tXdmMhSddSYr0w2Iqzn4wT3yza_1Jw
- X-Skirent-Signature
- t=1794680608,v1=947b98a12f0168d047e7b79a57f0a6ffe82681c1b2164c3175d176de0d2a4983
Rumpf, Byte für Byte
{"event":"course.booked","delivery":"01a1db4c-d50a-7497-8d47-2dfe466de15a","sentAt":"2026-11-14T18:23:28.010Z","tenant":"talstation","test":true,"course":{"uid":"00000000-0000-7000-8000-000000000000","bookingRef":"TEST-000000","status":"booked","provider":"eigen","courseId":"0","courseName":"Testkurs","variantId":"0","date":"2026-11-14","days":1,"timeFrom":"10:00","meetingPointId":null,"meetingPointName":"Testtreffpunkt","skillId":null,"skillName":null,"language":"de","persons":1,"participants":[{"firstName":"Erika","lastName":"Muster","age":30}],"contact":{"name":"Erika Muster","email":"erika@example.org","phone":"+43 000 000000"},"amountCents":0,"currency":"EUR","bookedAt":"2026-11-14T18:23:28.010Z","updatedAt":"2026-11-14T18:23:28.010Z","reportedAt":null}}Signiert wird
1794680608.{"event":"course.booked","delivery":"01a1db4c-d50a-7497-8d47-2df…Ergebnis
v1=947b98a12f0168d047e7b79a57f0a6ffe82681c1b2164c3175d176de0d2a4983Auf der Kommandozeile, mit dem Rumpf unverändert in der Datei rumpf.json und ohne Zeilenumbruch am Ende:
T="<der Wert von t aus dem Kopf>"SECRET="<das Geheimnis>"printf '%s.%s' "$T" "$(cat rumpf.json)" | openssl dgst -sha256 -hmac "$SECRET"Die Prüfung des Alters schlägt bei diesem Prüfwert an, weil er alt ist. Schalten Sie sie für den Test ab oder setzen Sie die Uhr des Tests auf t.
Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Anzeichen | Ursache |
|---|---|
| Die Signatur stimmt nie | Der Rumpf wurde vor dem Nachrechnen geparst und neu geschrieben. Ein Framework, das den Rumpf selbst liest, muss den rohen Text herausgeben. |
| Die Signatur stimmt nur manchmal | Umlaute: gerechnet wird über die Bytes in UTF-8, nicht über eine andere Kodierung. |
| Die Signatur stimmt seit heute nicht mehr | Das Geheimnis wurde im Portal erneuert. Das alte gilt nicht mehr. |
| Alles kommt doppelt | Die Gegenstelle antwortet zu langsam oder nicht mit 2xx. Dann wiederholt Ski4me. |