Webhook-Signaturprüfung mit persönlichen Secrets
Mit einem persönlichen Secret signiert Chaingateway jeden Webhook im Header X-Signature. So funktioniert die HMAC, mit einer Node.js-Prüfung und ihren Grenzen.
Geprüft von Maurice Sobiera
Ein persönliches Secret ist ein Schlüssel, den Sie in Ihrem Chaingateway-Profil setzen. Ist er vorhanden, trägt jeder ausgehende Webhook einen Header X-Signature. Dieser Header ist eine HMAC-SHA256 der Transaktions-ID, signiert mit diesem Secret und Base64-kodiert. Ihr Server berechnet den Wert neu und vergleicht ihn. So zeigt sich, dass die Anfrage von Chaingateway stammt.
Warum brauchen Webhooks eine Signatur?
Ein Webhook-Endpunkt ist eine öffentliche URL. Jeder, der sie kennt, kann eine Anfrage dorthin senden.
Ohne Prüfung könnte eine gefälschte Meldung „Zahlung eingegangen“ Ware freigeben oder ein Konto gutschreiben. Ein gemeinsames Secret löst das Problem. Nur Chaingateway und Ihr Server kennen den Schlüssel. Nur sie können deshalb eine passende Signatur erzeugen. Die Konstruktion ist HMAC, definiert in RFC 2104: eine Hash-Funktion kombiniert mit einem geheimen Schlüssel.
Wie setzen Sie ein persönliches Secret?
Öffnen Sie die Profileinstellungen im Dashboard, finden Sie die Karte für das persönliche Webhook-Secret und klicken Sie auf „Set Personal Secret“. Um ein bestehendes Secret zu ersetzen, klicken Sie auf „Regenerate Secret“. Zwei Details aus der Dokumentation sind wichtig:
- Ein erstmals gesetztes Secret aktiviert den Header
X-Signaturefür alle ausgehenden Webhooks. Stellen Sie sicher, dass Ihr Server den neuen Header akzeptiert und prüft, bevor Sie sich darauf verlassen. - Ein neu generiertes Secret wirkt sofort. Aktualisieren Sie Ihren Handler, bevor Sie klicken, oder im selben Moment. Sonst schlägt die Prüfung gültiger Benachrichtigungen fehl.
Wie wird die Signatur gebildet?
Das dokumentierte Verfahren hat drei Schritte. Lesen Sie das Feld txid aus dem Webhook-Payload. Berechnen Sie HMAC-SHA256 mit Ihrem persönlichen Secret als Schlüssel und dem String txid als Nachricht. Kodieren Sie das Ergebnis in Base64 und vergleichen Sie es mit dem Header. Ein Payload sieht so aus (aus dem Webhook-Leitfaden):
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}Wie prüfen Sie die Signatur auf Ihrem Server?
Berechnen Sie die HMAC aus der txid neu und vergleichen Sie sie mit dem Header in konstanter Zeit. Der folgende Express-Handler tut das. Er liest das Secret aus einer Umgebungsvariable, weist einen fehlenden oder falsch langen Header zurück und antwortet nur bei gültigen Anfragen mit 200:
const crypto = require('crypto');const express = require('express');
const app = express();app.use(express.json());
function isValid(txid, received, secret) { const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64'); const a = Buffer.from(expected); const b = Buffer.from(received || ''); // timingSafeEqual throws when lengths differ, so check first return a.length === b.length && crypto.timingSafeEqual(a, b);}
app.post('/hooks/deposit', (req, res) => { const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET); if (!ok) return res.sendStatus(401); // process req.body.txid, deduplicate on it, then acknowledge res.sendStatus(200);});
app.listen(3000);Die Dokumentation enthält außerdem Versionen für Python, Java und PHP. In Python nutzen Sie für den Vergleich hmac.compare_digest. In Node.js erledigt crypto.timingSafeEqual dieselbe Aufgabe. Ein einfacher Vergleich mit == kann Informationen über die Laufzeit preisgeben.
Wie testen Sie den Handler?
Berechnen Sie selbst eine Signatur und senden Sie eine gefälschte Benachrichtigung an Ihren lokalen Server. Der folgende openssl-Befehl erzeugt dieselbe Base64-HMAC, die der Handler erwartet. Verwenden Sie ein Test-Secret, niemals Ihr echtes:
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \ -H "Content-Type: application/json" \ -H "X-Signature: $SIG" \ -d "{\"txid\": \"$TXID\"}"Starten Sie den Server mit CG_PERSONAL_SECRET=test-secret. Die Anfrage liefert 200. Ändern Sie ein einziges Zeichen des Secrets oder der Signatur, und die Antwort ist 401. Wiederholen Sie diesen Test nach jedem Deployment des Handlers und nach jeder Neugenerierung Ihres echten Secrets.
Was deckt die Signatur nicht ab?
Sie deckt die Transaktions-ID ab und sonst nichts. Laut dem dokumentierten Verfahren geht nur txid in die HMAC ein. Daraus folgen zwei Konsequenzen:
- Eine gültige Signatur belegt, dass Chaingateway eine Benachrichtigung für diese Transaktion gesendet hat. Sie belegt nicht, dass
amount,toodercontractaddressim Body unverändert sind. Wenn diese Felder eine Auszahlung bestimmen, prüfen Sie sie gegen die Chain oder gegen die erwarteten Werte der Bestellung. - Dieselbe Transaktion kann mehr als einmal eintreffen, etwa nachdem Sie das erneute Senden einer fehlgeschlagenen Benachrichtigung angefordert haben. Jede Kopie trägt dieselbe gültige Signatur. Deduplizieren Sie deshalb über
txid.
Webhooks werden nicht automatisch wiederholt. Fehlgeschlagene Benachrichtigungen sind pro Chain aufgelistet, und Sie fordern das erneute Senden für jede einzelne an. Solana hat keine Webhooks. Wo Webhooks existieren, funktioniert die Signatur auf jeder Chain gleich.
Wie rotieren Sie das Secret, ohne Benachrichtigungen zu verlieren?
Ein neu generiertes Secret wirkt sofort. Deshalb zählt die Reihenfolge der Schritte. Lassen Sie den Handler für eine kurze Zeit zwei Secrets akzeptieren und generieren Sie danach neu:
- Deployen Sie eine Handler-Version, die zuerst das aktuelle Secret prüft. Schlägt diese Prüfung fehl, prüft sie zusätzlich ein zweites, optionales
CG_PERSONAL_SECRET_NEXT. - Generieren Sie das Secret in Ihrem Profil neu und kopieren Sie den neuen Wert.
- Tragen Sie den neuen Wert in
CG_PERSONAL_SECRET_NEXTein und deployen Sie erneut. - Senden Sie im Testnetz einen Testtransfer und prüfen Sie, dass der Handler ihn akzeptiert.
- Nach einem Tag übernehmen Sie das neue Secret in
CG_PERSONAL_SECRETund entfernen das alte.
Die Dokumentation sagt nicht, welches Secret eine Benachrichtigung signiert, die Sie nach einer Rotation erneut senden. Halten Sie das Fenster mit zwei Secrets offen, bis die Liste der fehlgeschlagenen Benachrichtigungen leer ist.
Was passiert, wenn Sie kein Secret gesetzt haben?
Dann senden Webhooks ohne den Header X-Signature. Ihr Handler darf einen fehlenden Header nicht als gültig behandeln. Entscheiden Sie je Umgebung: In der Produktion lehnen Sie Anfragen ohne Signatur ab, sobald Sie ein Secret gesetzt haben. In einer lokalen Testumgebung dürfen Sie sie zulassen. Der Header zeigt außerdem, ob ein Secret aktiv ist. Eine Benachrichtigung ohne Header bedeutet, dass auf Ihrem Konto kein Secret gesetzt ist.
Wo finden Sie die vollständige Referenz?
Der Leitfaden zur Webhook-Sicherheit listet die Schritte und den Code in vier Sprachen. Der Webhook-Leitfaden erklärt, wie Sie Webhooks und Empfänger anlegen.
Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.