Webhooki

RolChat dostarcza zdarzenia do Twoich systemów jako podpisane żądania HTTP POST. Ta strona opisuje webhooki wtyczek; webhooki wysyłane przez regułę Automatyzacji różnią się ponowieniami, czasem oczekiwania i rotacją sekretu, zobacz Webhooki automatyzacji. Te same zasady obowiązują w drugą stronę, gdy Twój system, wtyczka lub dostawca wysyła dane do RolChat. Zweryfikuj każde dostarczenie w poniższej kolejności, zanim na nie zareagujesz.

Jak wygląda dostarczenie

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": { … } }

Nagłówek	Znaczenie
X-RolChat-Timestamp	Sekundy Unix w chwili wysłania. Część podpisywanej wiadomości.
X-RolChat-Signature	sha256=<hex>. Prefiks wskazuje algorytm, aby można go było później zmienić.
X-RolChat-Nonce	ULID unikalny dla tego żądania HTTP. Ponowienie dostaje nowy nonce.
X-RolChat-Event-Id	Własny identyfikator zdarzenia. Stały przy ponowieniach; używaj go do deduplikacji.

Dostarczenia wychodzące trafiają tylko do endpointów HTTPS. URL HTTP jest odrzucany przy tworzeniu subskrypcji.

Podpis

Podpisywana wiadomość to znacznik czasu, dosłowna kropka i surowa treść żądania, bajt w bajt:

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

Podpisuj otrzymane bajty, a nie ponownie zserializowaną kopię sparsowanego JSON. Zmiany białych znaków lub kolejności kluczy psują podpis. SHA-256 to jedyny akceptowany algorytm.

Akcja automatyzacji „Wyślij żądanie HTTP”

Żądania wysyłane przez akcję HTTP modułu Automatyzacja są podpisane dwoma nagłówkami. X-RolChat-Signature to sha256= plus HMAC-SHA256 samej treści. X-RolChat-Signature-V2 to HMAC-SHA256 z <timestamp>.<body>, czyli schemat opisany powyżej, ze znacznikiem czasu z X-RolChat-Timestamp. Weryfikuj nagłówek V2; nagłówek z podpisem samej treści nie chroni przed ponownym odtworzeniem żądania. Te żądania nie zawierają X-RolChat-Nonce ani X-RolChat-Event-Id; każda próba jednego dostarczenia ma ten sam X-RolChat-Delivery-Id i własny numer w X-RolChat-Attempt, więc pomiń kontrolę nonce i deduplikuj według X-RolChat-Delivery-Id. Przykłady weryfikacji czytają X-RolChat-Signature: dla żądań automatyzacji czytaj zamiast tego X-RolChat-Signature-V2.

Weryfikacja dostarczenia

Wykonaj te pięć kontroli w podanej kolejności. Przykłady w Pythonie, Node.js, Go, Ruby i PHP są na stronie przykładów weryfikacji.

1. Świeżość. Odrzuć, jeśli |now − X-RolChat-Timestamp| > 300 sekund (400). Pięć minut toleruje rozbieżność zegarów, a przechwycone żądanie traci po tym czasie wartość. Synchronizuj serwer przez NTP.
2. Podpis. Oblicz oczekiwaną wartość i porównaj ją w stałym czasie (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Przy niezgodności odrzuć z 401. Zwykłe porównanie ciągów ujawnia informacje przez czas wykonania i jest niedopuszczalne.
3. Nonce. Zapisz X-RolChat-Nonce z TTL 10 minut, używając atomowego zapisu, jeśli klucz nie istnieje (SET NX EX 600). Jeśli już istnieje, odrzuć z 409: to powtórzenie. Jeśli magazyn nonce nie działa, odmów bezpiecznie z 503, aby RolChat ponowił próbę; nigdy nie przechodź do „akceptuj”.
4. Parsuj treść dopiero teraz.
5. Deduplikuj według identyfikatora zdarzenia. Ponowienia mają nowy nonce, ale ten sam X-RolChat-Event-Id. Jeśli ten identyfikator został przetworzony w ciągu ostatnich siedmiu dni, odpowiedz 200 bez ponownego przetwarzania.

Odpowiedz 2xx, gdy tylko dostarczenie zostanie bezpiecznie przyjęte; pracę wykonaj asynchronicznie. RolChat czeka na odpowiedź 15 sekund.

Sekrety

• Sekret webhooka to 64 losowe bajty zakodowane w base64url (około 86 znaków). Jest generowany przy tworzeniu subskrypcji lub wtyczki i pokazywany raz.
• Przechowuj go we własnym sejfie lub zmiennej środowiskowej; RolChat przechowuje tylko zaszyfrowaną kopię.
• Zaleca się zmianę po 90 dniach; produkt pokazuje przypomnienie, ale nigdy nie wyłącza subskrypcji z powodu braku zmiany.
• Zmiana korzysta z okna nakładania się: po POST /api/v1/plugins/{id}/webhook-secret/rotate przez siedem dni weryfikują się zarówno stary, jak i nowy sekret, nowe dostarczenia są podpisywane nowym, a stary jest usuwany po upływie okna. W chwili zmiany nic się nie psuje.
• Jeśli sekret wycieknie, POST /api/v1/plugins/{id}/webhook-secret/revoke natychmiast go unieważnia, wydaje nowy, wysyła e-mail do administratorów konta i zapisuje wpis w audycie.

Ponowienia i martwe wiadomości

Odpowiedź inna niż 2xx lub awaria sieci planuje ponowienie:

Próba	Opóźnienie po poprzedniej
1	natychmiast
2	15 sekund
3	1 minuta
4	5 minut
5	30 minut
6	2 godziny
7	8 godzin
8	24 godziny

408, 429, 5xx i błędy sieci są ponawiane. 400, 401, 403, 404 i 410 nie są: dostarczenie trafia od razu do kolejki martwych wiadomości, bo ponawianie odrzuconego podpisu lub nieistniejącego endpointu nie może pomóc. Po ośmiu nieudanych próbach dostarczenie również trafia do kolejki martwych wiadomości.

Martwe wiadomości są przechowywane 30 dni i widoczne w Ustawienia → Wtyczki → {plugin} → Log webhooków → DLQ, gdzie administrator może ponownie wysłać wybraną (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limity

• Treść wychodząca: domyślnie 1 MB (konfigurowalne dla każdej wtyczki). Treść przychodząca do RolChat: 5 MB. Większa daje 413.
• Wtyczka może zadeklarować allowed_source_ips; RolChat stosuje tę listę dozwolonych przed weryfikacją.
• Możesz dodatkowo sprawdzać user agent RolChat-Webhook/1.0 jako kontrolę poprawności. Nie jest to mechanizm bezpieczeństwa.

Webhooki przychodzące do RolChat

Dostawcy wysyłają dane do RolChat na /api/v1/webhooks/{category}/{adapter}, używając własnych schematów podpisów (Twilio, Telnyx, Bandwidth, Meta dla WhatsApp, Stripe). Każdy adapter weryfikuje podpis swojego dostawcy, normalizuje treść i publikuje ją ponownie na wewnętrznej magistrali zdarzeń z podpisem RolChat. Twój własny system może wysyłać dane do RolChat z tymi samymi nagłówkami X-RolChat-* opisanymi powyżej, podpisane sekretem wtyczki, do której należy endpoint.

Webhooki automatyzacji

Akcja Wyślij żądanie HTTP modułu Automatyzacja ma własne zasady dostarczania:

• Jeden sekret na konto. Pokaż go lub zrotuj na ekranie Automatyzacji (Właściciel i Administrator). Rotacja działa natychmiast: nie ma okresu nakładania się, stary sekret przestaje być weryfikowany od razu, więc najpierw zaktualizuj odbiorcę albo zaakceptuj krótką lukę.
• Czas oczekiwania: RolChat czeka na odpowiedź 10 sekund.
• Ponowienia: maksymalnie 6 prób łącznie. Przerwa przed próbą 2 wynosi 30 sekund, potem około 2 minuty, 8 minut, 32 minuty i 2 godziny 8 minut, każda z odchyleniem do 20 %. Pojedyncza przerwa nigdy nie przekracza 6 godzin.
• Co jest ponawiane: błędy sieci, przekroczenia czasu, 5xx, 408, 425 i 429. Inne odpowiedzi 4xx, zablokowany adres lub zbyt duża treść nie są ponawiane: dostarczenie trafia od razu do kolejki martwych wiadomości, tak samo jak po ostatniej nieudanej próbie.
• Nagłówki: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testowanie odbiorcy

POST /api/v1/webhooks/test-signature wysyła syntetyczne podpisane zdarzenie na endpoint wywołującej wtyczki, aby można było sprawdzić implementację od początku do końca, zanim pojawi się prawdziwy ruch.

Typowe błędy

• Weryfikacja względem sparsowanego i ponownie zakodowanego JSON zamiast surowych bajtów.
• Porównywanie podpisów operatorem ==.
• Deduplikacja według nonce (każde ponowienie ma nowy) zamiast według identyfikatora zdarzenia.
• Zegar przesunięty o ponad pięć minut.
• Wykonywanie powolnej pracy przed odpowiedzią, a w efekcie przekroczenie 15 sekund i ponowne otrzymanie tego samego zdarzenia.