Webhooks

Statt zu fragen, wirst du informiert. Ryh sendet Ereignisse an deinen Empfänger – signiert, wiederholbar und pro Umgebung getrennt.

Ereignisse

Verfügbare Webhook-Ereignisse
Ereignis	Bedeutung	Wann	Bereich
connection.created	Verbindung angelegt	Ein Betrieb verbindet einen Connector.	Netz
connection.paused	Verbindung pausiert	Eine Verbindung wurde vorübergehend gestoppt.	Netz
capability.denied	Fähigkeit abgelehnt	Eine angefragte Fähigkeit ist nicht freigegeben.	Netz
webhook.test	Testereignis	Manuell ausgelöst, um eine Anbindung zu prüfen.	Test

Signatur prüfen

HMAC-SHA256 über Zeitstempel und unveränderten Rohtext der Anfrage

Schritte

Zeitstempel aus dem Kopf lesen und Abweichungen über fünf Minuten ablehnen.
Rohtext der Anfrage unverändert verwenden – nicht vorher als JSON verarbeiten.
Prüfwert mit dem eigenen Empfängerschlüssel bilden.
Vergleich zeitkonstant durchführen und bei Abweichung mit 401 antworten.

Der Empfängerschlüssel wird nur einmal bei der Erstellung angezeigt.
In der Dokumentation stehen keine echten Signaturen oder Schlüssel.
Ein zweiter Schlüssel kann während einer Rotation parallel gültig sein.

Prüfung im Empfänger

const roh = await request.text();
const zeit = request.headers.get("X-Ryh-Timestamp");
const signatur = request.headers.get("X-Ryh-Signature");

const erwartet = hmacSha256(empfaengerSchluessel, zeit + "." + roh);
if (!zeitkonstantGleich(signatur, erwartet)) {
  return new Response("Signatur passt nicht", { status: 401 });
}

const ereignis = JSON.parse(roh);

Wiederholungen

Exponentiell mit Streuung, beginnend im Sekundenbereich

Bis zu 6 Versuche. Nach dem letzten Versuch wandert das Ereignis in die Nachbearbeitung und kann erneut ausgelöst werden.

Innerhalb von fünf Sekunden mit 2xx antworten.
Langlaufende Arbeit nach der Antwort erledigen.
Ereignisse anhand ihrer Kennung entdoppeln – Zustellungen können sich wiederholen.

Wenn etwas nicht ankommt

Häufige Zustellprobleme
Antwort	Bedeutung	Lösung
401	Signatur passt nicht	Rohtext und Schlüssel prüfen, Rotation abschließen.
404	Empfänger nicht erreichbar	Adresse im Portal aktualisieren.
5xx	Empfänger meldet Fehler	Zustellung wird wiederholt; Nachbearbeitung im Portal prüfen.
Zeitüberschreitung	Keine Antwort in fünf Sekunden	Verarbeitung asynchron aufbauen.

Sicherer Betrieb

Nur HTTPS-Empfänger zulassen.
Signatur prüfen, bevor der Inhalt gelesen wird.
Keine Geheimnisse in Protokolldateien schreiben.
Empfänger je Umgebung trennen: Sandbox niemals auf produktive Systeme richten.

Empfängerschlüssel werden nur einmal angezeigt. Beim Rotieren bleiben zwei Schlüssel kurzzeitig gültig.