Checkout-Webhooks absichern: API-Key und Signatur in Make, Zapier und n8n

Mit dem Rechnungskit-Checkout verkaufst du über einen Link, die Rechnung entsteht automatisch. Was nach dem Kauf passiert, steuerst du über einen Webhook: Zugang freischalten, Lizenz erzeugen, den Versand anstoßen, in Make, Zapier oder n8n weiterverarbeiten. Diese Seite zeigt, wie du deinen Webhook-Empfänger so einrichtest, dass er nur echte Nachrichten von Rechnungskit akzeptiert.

Was Rechnungskit sendet

Rechnungskit schickt bei jedem Ergebnis eines Checkouts einen POST-Request mit JSON-Body an deine URL, bei Erfolg als checkout.paid, bei Fehlschlag als checkout.failed. Jede Nachricht trägt diese Header:

Zugestellt wird mindestens einmal: Antwortet dein Empfänger nicht mit einem 2xx-Status, versucht es Rechnungskit bis zu sechsmal mit wachsendem Abstand erneut. Mit dem Button "Test-Ereignis senden" am Webhook prüfst du die ganze Strecke mit einem Beispiel-Event, ohne einen echten Kauf auszulösen.

Zwei Sicherungswege: API-Key und Signatur

Deine Webhook-URL ist bereits die erste Sicherung: Sie enthält einen langen Zufallsanteil und ist praktisch nicht erratbar. Wer es genauer möchte, hat zwei Stufen:

1. API-Key (einfach): Beim Anlegen des Webhooks in Rechnungskit trägst du einen frei gewählten Key ein. Er wird bei jeder Zustellung als Header mitgeschickt. Dein Empfänger vergleicht nur noch den Wert, ganz ohne Kryptografie. Das ist der richtige Weg für Make, Zapier und n8n.
2. HMAC-Signatur (stark): Rechnungskit signiert den exakten JSON-Body mit deinem Signatur-Secret (whsec_…, wird beim Anlegen genau einmal angezeigt). Wer die Signatur nachrechnet, weiß sicher, dass die Nachricht von Rechnungskit stammt und nicht verändert wurde. Das ist der richtige Weg für eigenen Code und für Empfänger mit Krypto-Unterstützung.

Make: API-Key-Authentifizierung

Make prüft API-Keys nativ am Custom Webhook und erwartet den Key im Header x-make-apikey. Genau dorthin schickt Rechnungskit deinen Key automatisch, es ist also keine Umbenennung oder Zwischenlogik nötig.

1. Lege in deinem Szenario das Modul Webhooks, Custom webhook an (oder öffne deinen bestehenden Webhook) und öffne die erweiterten Einstellungen des Webhooks.
2. Klicke bei API Key authentication auf Add API key und lege einen neuen Schlüsselbund (Keychain) an. Trage dort exakt den Key ein, den du in Rechnungskit beim Anlegen des Webhooks als API-Key gesetzt hast. Make zeigt den Wert danach aus Sicherheitsgründen nicht mehr an.
3. Speichere. Ab jetzt beantwortet Make jede Nachricht ohne passenden Key mit HTTP 401, dein Szenario startet nur noch für echte Rechnungskit-Events.

Zwei nützliche Extras in denselben Webhook-Einstellungen: IP restrictions (eine kommagetrennte Liste erlaubter Absender-IPs) und Get request headers, falls du Header-Werte im Szenario weiterverwenden möchtest. Die HMAC-Signatur lässt sich in Make ebenfalls nachrechnen (die Funktion sha256 akzeptiert einen Key-Parameter und liefert dann ein HMAC), dafür müssen aber JSON-Pass-through und Header-Übernahme aktiv sein und ein Filter die Werte vergleichen. Für Make empfehlen wir den API-Key.

n8n: Header Auth

Der Webhook-Knoten von n8n bringt die Header-Prüfung als eigene Authentifizierungsart mit:

1. Öffne deinen Webhook-Knoten und stelle Authentication auf Header Auth.
2. Lege unter Credential for Header Auth eine neue Credential vom Typ Header Auth an. Als Name trägst du X-Api-Key ein, als Value deinen in Rechnungskit gesetzten API-Key. Die Groß- und Kleinschreibung des Header-Namens spielt keine Rolle.
3. Speichere und aktiviere den Workflow. Nachrichten ohne passenden Key lehnt n8n mit HTTP 403 ab.

Wenn du stattdessen die Signatur prüfen willst: Aktiviere am Webhook-Knoten die Option Raw Body, damit der exakte Body erhalten bleibt. Danach berechnet entweder der Crypto-Knoten (Action Hmac, Type SHA256, Encoding HEX, Secret = dein whsec_…) oder ein Code-Knoten mit require('crypto') die Signatur, und ein IF-Knoten vergleicht "sha256=" + hmac mit dem Header x-rechnungskit-signature.

Zapier: Catch Raw Hook und Filter

Zapier hat keine eingebaute Key-Prüfung am Webhook-Trigger; die unerratbare Catch-URL ist dort die Standard-Sicherung. Wenn du zusätzlich den API-Key prüfen willst, brauchst du den Trigger-Typ mit Headern:

1. Verwende als Trigger Webhooks by Zapier mit dem Event Catch Raw Hook (nicht Catch Hook: der normale Catch Hook parst nur den Body und liefert keine Header). Catch Raw Hook setzt einen kostenpflichtigen Zapier-Plan voraus.
2. Löse ein Test-Event aus ("Test-Ereignis senden" in Rechnungskit), damit Zapier die Struktur kennt. Die Header erscheinen mit Unterstrichen, dein Key steht also im Feld headers X_Api_Key.
3. Füge direkt nach dem Trigger einen Filter by Zapier ein: Only continue if, Feld X_Api_Key, Bedingung (Text) Exactly matches, Wert = dein API-Key.

Auch die Signatur lässt sich in Zapier prüfen: Der Catch Raw Hook liefert den unveränderten Body im Feld raw, ein Code by Zapier-Schritt (Python mit hmac/hashlib oder JavaScript mit crypto) berechnet daraus die Signatur und gibt ein Vergleichsergebnis aus, auf das der Filter prüft. Für die meisten Zaps ist der API-Key-Filter der pragmatische Weg.

Die Signatur selbst prüfen (HMAC-SHA256)

Für eigene Endpunkte (dein Server, eine Cloud Function, der n8n-Code-Knoten) rechnest du die Signatur über den unveränderten Request-Body nach, mit dem Signatur-Secret aus der Webhook-Einrichtung:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
	const expected =
		'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
	return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Drei Stolpersteine aus der Praxis: Erstens muss wirklich der rohe Body gehasht werden, nicht ein neu serialisiertes JSON (schon eine andere Feldreihenfolge ändert die Signatur). Zweitens ist der Vergleich mit timingSafeEqual dem einfachen === vorzuziehen. Drittens lohnt sich die Dubletten-Erkennung über die Event-ID: Rechnungskit stellt mindestens einmal zu, bei Wiederholungen kommt dieselbe X-Rechnungskit-Event-Id erneut.