Webhooks

RolChat stellt Ereignisse als signierte HTTP-POST-Anfragen an Ihre Systeme zu. Diese Seite beschreibt Plugin-Webhooks; Webhooks, die eine Automatisierungs-Regel sendet, unterscheiden sich bei Wiederholungen, Wartezeit und Rotation des Geheimnisses, siehe Automatisierungs-Webhooks. Dieselben Regeln gelten in umgekehrter Richtung, wenn Ihr System, ein Plugin oder ein Anbieter an RolChat sendet. Verifizieren Sie jede Zustellung in der unten beschriebenen Reihenfolge, bevor Sie darauf reagieren.

So sieht eine Zustellung aus

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

Header	Bedeutung
`X-RolChat-Timestamp`	Unix-Sekunden zum Zeitpunkt des Versands. Teil der signierten Nachricht.
`X-RolChat-Signature`	`sha256=<hex>`. Das Präfix benennt den Algorithmus, damit er sich später ändern kann.
`X-RolChat-Nonce`	Eine ULID, eindeutig für diese HTTP-Anfrage. Eine Wiederholung erhält eine neue Nonce.
`X-RolChat-Event-Id`	Die eigene ID des Ereignisses. Stabil über Wiederholungen; verwenden Sie sie zur Deduplizierung.

Ausgehende Zustellungen gehen nur an HTTPS-Endpunkte. Eine HTTP-URL wird beim Anlegen des Abonnements abgelehnt.

Die Signatur

Die signierte Nachricht besteht aus dem Zeitstempel, einem wörtlichen Punkt und dem unveränderten Request-Body, Byte für Byte:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

Signieren Sie die empfangenen Bytes, nicht eine neu serialisierte Kopie des geparsten JSON. Änderungen an Leerzeichen oder der Reihenfolge der Schlüssel machen die Signatur ungültig. SHA-256 ist der einzige akzeptierte Algorithmus.

Anfragen, die die HTTP-Aktion des Moduls Automatisierung sendet, werden mit zwei Headern signiert. X-RolChat-Signature ist sha256= plus das HMAC-SHA256 nur des Bodys. X-RolChat-Signature-V2 ist das HMAC-SHA256 von <timestamp>.<body>, das oben beschriebene Verfahren, mit X-RolChat-Timestamp als Zeitstempel. Prüfen Sie den V2-Header; der Header nur für den Body schützt nicht vor einer wiederholten Anfrage. Diese Anfragen tragen kein X-RolChat-Nonce und keine X-RolChat-Event-Id; alle Versuche einer Zustellung tragen dieselbe X-RolChat-Delivery-Id und in X-RolChat-Attempt ihre eigene Nummer, überspringen Sie also die Nonce-Prüfung und deduplizieren Sie nach X-RolChat-Delivery-Id. Die Verifizierungsbeispiele lesen X-RolChat-Signature: Lesen Sie bei Automatisierungsanfragen stattdessen X-RolChat-Signature-V2.

Zustellung verifizieren

Führen Sie diese fünf Prüfungen der Reihe nach durch. Beispiele in Python, Node.js, Go, Ruby und PHP stehen auf der Seite Verifizierungsbeispiele.

Aktualität. Ablehnen, wenn |now − X-RolChat-Timestamp| > 300 Sekunden (400). Fünf Minuten tolerieren Abweichungen der Uhr und machen eine abgefangene Anfrage danach wertlos. Halten Sie Ihren Server per NTP synchron.
Signatur. Berechnen Sie den erwarteten Wert und vergleichen Sie ihn mit einem Vergleich in konstanter Zeit (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Bei Abweichung mit 401 ablehnen. Ein einfacher Stringvergleich verrät Zeitinformationen und ist nicht akzeptabel.
Nonce. Speichern Sie X-RolChat-Nonce mit einer TTL von 10 Minuten über ein atomares Setzen-wenn-nicht-vorhanden (SET NX EX 600). Existiert sie bereits, mit 409 ablehnen: Die Anfrage ist ein Replay. Ist Ihr Nonce-Speicher nicht erreichbar, schlagen Sie sicher mit 503 fehl, damit RolChat es erneut versucht; fallen Sie nie auf „Akzeptieren“ zurück.
Parsen Sie den Body erst jetzt.
Nach Ereignis-ID deduplizieren. Wiederholungen tragen eine neue Nonce, aber dieselbe X-RolChat-Event-Id. Haben Sie diese ID in den letzten sieben Tagen verarbeitet, antworten Sie mit 200, ohne erneut zu verarbeiten.

Antworten Sie mit 2xx, sobald die Zustellung sicher angenommen ist; erledigen Sie die Arbeit asynchron. RolChat wartet 15 Sekunden auf eine Antwort.

Geheimnisse

Ein Webhook-Geheimnis besteht aus 64 zufälligen Bytes, base64url-kodiert (etwa 86 Zeichen). Es wird beim Anlegen des Abonnements oder Plugins erzeugt und einmal angezeigt.
Bewahren Sie es in Ihrem eigenen Tresor oder Ihrer Umgebung auf; RolChat speichert nur eine verschlüsselte Kopie.
Eine Rotation wird nach 90 Tagen empfohlen; das Produkt zeigt eine Erinnerung, deaktiviert ein Abonnement aber nie wegen fehlender Rotation.
Die Rotation nutzt ein Überlappungsfenster: Nach POST /api/v1/plugins/{id}/webhook-secret/rotate sind sieben Tage lang sowohl das alte als auch das neue Geheimnis gültig, neue Zustellungen werden mit dem neuen signiert, und das alte wird nach dem Fenster gelöscht. Im Moment der Rotation geht nichts kaputt.
Ist ein Geheimnis kompromittiert, macht POST /api/v1/plugins/{id}/webhook-secret/revoke es sofort ungültig, stellt ein neues aus, benachrichtigt die Administratoren des Kontos per E-Mail und schreibt einen Audit-Eintrag.

Wiederholungen und Dead Letters

Eine Antwort, die nicht 2xx ist, oder ein Netzwerkfehler plant eine Wiederholung ein:

Versuch	Verzögerung nach dem vorherigen
1	sofort
2	15 Sekunden
3	1 Minute
4	5 Minuten
5	30 Minuten
6	2 Stunden
7	8 Stunden
8	24 Stunden

408, 429, 5xx und Netzwerkfehler werden wiederholt. 400, 401, 403, 404 und 410 nicht: Die Zustellung geht direkt in die Dead-Letter-Queue, weil eine Wiederholung bei einer abgelehnten Signatur oder einem fehlenden Endpunkt nicht helfen kann. Nach acht fehlgeschlagenen Versuchen landet die Zustellung ebenfalls in der Dead-Letter-Queue.

Dead Letters werden 30 Tage aufbewahrt und sind unter Einstellungen → Plugins → {plugin} → Webhook-Protokoll → DLQ sichtbar, wo ein Administrator einen Eintrag erneut abspielen kann (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limits

Ausgehender Body: standardmäßig 1 MB (pro Plugin konfigurierbar). Eingehender Body an RolChat: 5 MB. Größer ergibt 413.
Ein Plugin kann allowed_source_ips deklarieren; RolChat wendet diese Allowlist vor der Verifizierung an.
Sie können zusätzlich den User-Agent RolChat-Webhook/1.0 als Plausibilitätsprüfung festlegen. Eine Sicherheitsmaßnahme ist das nicht.

Eingehende Webhooks an RolChat

Anbieter senden an RolChat unter /api/v1/webhooks/{category}/{adapter} mit ihren eigenen Signaturverfahren (Twilio, Telnyx, Bandwidth, Meta für WhatsApp, Stripe). Jeder Adapter verifiziert die Signatur seines Anbieters, normalisiert die Payload und veröffentlicht sie mit einer RolChat-Signatur erneut auf dem internen Ereignisbus. Ihr eigenes System kann mit denselben oben beschriebenen Headern X-RolChat-* an RolChat senden, signiert mit dem Geheimnis des Plugins, dem der Endpunkt gehört.

Automatisierungs-Webhooks

Die Aktion HTTP-Anfrage senden des Moduls Automatisierung hat eigene Zustellregeln:

Ein Geheimnis pro Konto. Zeigen Sie es auf dem Bildschirm Automatisierung an oder rotieren Sie es (Inhaber und Administrator). Die Rotation wirkt sofort: Es gibt kein Überlappungsfenster, das alte Geheimnis wird sofort nicht mehr verifiziert; aktualisieren Sie also zuerst Ihren Empfänger oder nehmen Sie eine kurze Lücke in Kauf.
Wartezeit: RolChat wartet 10 Sekunden auf eine Antwort.
Wiederholungen: insgesamt bis zu 6 Versuche. Die Pause vor Versuch 2 beträgt 30 Sekunden, danach etwa 2 Minuten, 8 Minuten, 32 Minuten und 2 Stunden 8 Minuten, jeweils um bis zu 20 % variiert. Eine einzelne Pause überschreitet nie 6 Stunden.
Was wiederholt wird: Netzwerkfehler, Timeouts, 5xx, 408, 425 und 429. Andere 4xx-Antworten, eine blockierte Adresse oder ein zu großer Body werden nicht wiederholt: Die Zustellung geht direkt in die Dead-Letter-Queue, ebenso wie nach dem letzten fehlgeschlagenen Versuch.
Header: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Den Empfänger testen

POST /api/v1/webhooks/test-signature sendet ein synthetisches signiertes Ereignis an den Endpunkt des aufrufenden Plugins, damit Sie Ihre Implementierung durchgängig prüfen können, bevor echter Traffic eintrifft.

Häufige Fehler

Verifizierung gegen das geparste und neu kodierte JSON statt gegen die unveränderten Bytes.
== zum Vergleich von Signaturen verwenden.
Nach Nonce deduplizieren (jede Wiederholung hat eine neue) statt nach Ereignis-ID.
Eine Uhr, die mehr als fünf Minuten abweicht.
Langsame Arbeit vor der Antwort erledigen, dann nach 15 Sekunden in ein Timeout laufen und dasselbe Ereignis erneut erhalten.