Webhooks
Statt zu fragen, wirst du informiert. Ryh sendet Ereignisse an deinen Empfänger – signiert, wiederholbar und pro Umgebung getrennt.
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.
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
| 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.