Webhook-lar

RolChat hadisələri sistemlərinizə imzalı HTTP POST sorğuları kimi çatdırır. Bu səhifə plagin webhook-larını təsvir edir; Avtomatlaşdırma qaydasının göndərdiyi webhook-lar təkrar cəhdlərə, gözləmə müddətinə və məxfi açarın dəyişdirilməsinə görə fərqlənir, bax: Avtomatlaşdırma webhook-ları. Eyni qaydalar əks istiqamətdə də tətbiq olunur: sisteminiz, plagin və ya provayder RolChat-ə məlumat göndərəndə. Hər çatdırılmanı onun əsasında hərəkət etməzdən əvvəl aşağıdakı ardıcıllıqla yoxlayın.

Çatdırılma necə görünür

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

Başlıq	Mənası
`X-RolChat-Timestamp`	Göndərmə anındakı Unix saniyələri. İmzalanmış mesajın bir hissəsidir.
`X-RolChat-Signature`	`sha256=<hex>`. Prefiks alqoritmi adlandırır ki, sonradan dəyişə bilsin.
`X-RolChat-Nonce`	Bu HTTP sorğusu üçün unikal ULID. Təkrar cəhd yeni nonce alır.
`X-RolChat-Event-Id`	Hadisənin öz ID-si. Təkrar cəhdlərdə dəyişmir; dublikatların aradan qaldırılması üçün istifadə edin.

Gedən çatdırılmalar yalnız HTTPS endpoint-lərinə göndərilir. Abunəlik yaradılarkən HTTP URL rədd edilir.

İmza

İmzalanan mesaj vaxt damğası, hərfi nöqtə və sorğunun xam gövdəsidir, bayt-bayt:

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

Aldığınız baytları imzalayın, təhlil edilmiş JSON-un yenidən seriyalaşdırılmış surətini yox. Boşluqların və ya açarların sırasının dəyişməsi imzanı pozur. SHA-256 qəbul edilən yeganə alqoritmdir.

Avtomatlaşdırma modulunun HTTP əməliyyatı ilə göndərilən sorğular iki başlıqla imzalanır. X-RolChat-Signature sha256= üstəgəl yalnız gövdənin HMAC-SHA256 qiymətidir. X-RolChat-Signature-V2 isə yuxarıda təsvir olunan sxem üzrə <timestamp>.<body> ifadəsinin HMAC-SHA256 qiymətidir; vaxt damğası kimi X-RolChat-Timestamp istifadə olunur. V2 başlığını yoxlayın; yalnız gövdəyə əsaslanan başlıq təkrar göndərilmiş sorğudan qorumur. Bu sorğularda X-RolChat-Nonce və X-RolChat-Event-Id yoxdur; bir çatdırılmanın bütün cəhdləri eyni X-RolChat-Delivery-Id və X-RolChat-Attempt daxilində öz nömrəsini daşıyır, ona görə nonce yoxlanmasını buraxın və X-RolChat-Delivery-Id üzrə dublikatları aradan qaldırın. Yoxlama nümunələri X-RolChat-Signature oxuyur: avtomatlaşdırma sorğuları üçün əvəzinə X-RolChat-Signature-V2 oxuyun.

Çatdırılmanın yoxlanması

Bu beş yoxlamanı ardıcıl edin. Python, Node.js, Go, Ruby və PHP nümunələri yoxlama nümunələri səhifəsindədir.

Təzəlik. |now − X-RolChat-Timestamp| > 300 saniyədirsə, rədd edin (400). Beş dəqiqə saat fərqinə dözür və ələ keçirilmiş sorğunu bundan sonra dəyərsiz edir. Serverinizi NTP ilə sinxron saxlayın.
İmza. Gözlənilən dəyəri hesablayın və sabit vaxtlı müqayisə ilə müqayisə edin (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Uyğunsuzluqda 401 ilə rədd edin. Sadə sətir müqayisəsi vaxt məlumatını sızdırır və qəbuledilməzdir.
Nonce. X-RolChat-Nonce dəyərini atomik “yoxdursa təyin et” əməliyyatı (SET NX EX 600) ilə 10 dəqiqəlik TTL ilə saxlayın. Artıq mövcuddursa, 409 ilə rədd edin: sorğu təkrar göndərmədir. Nonce anbarınız işləmirsə, RolChat-in təkrar cəhd etməsi üçün 503 ilə təhlükəsiz şəkildə uğursuz olun; heç vaxt “qəbul et” vəziyyətinə keçməyin.
Gövdəni yalnız indi təhlil edin.
Hadisə ID-si üzrə dublikatları aradan qaldırın. Təkrar cəhdlər yeni nonce, lakin eyni X-RolChat-Event-Id daşıyır. Həmin ID-ni son yeddi gündə emal etmisinizsə, yenidən emal etmədən 200 cavabı verin.

Çatdırılma təhlükəsiz qəbul edilən kimi 2xx cavabı verin; işi asinxron görün. RolChat cavab üçün 15 saniyə gözləyir.

Gizli açarlar

Webhook gizli açarı base64url ilə kodlaşdırılmış 64 təsadüfi baytdır (təxminən 86 simvol). O, abunəlik və ya plagin yaradılanda generasiya olunur və bir dəfə göstərilir.
Onu öz vault-unuzda və ya mühit dəyişənlərinizdə saxlayın; RolChat yalnız şifrələnmiş surəti saxlayır.
90 gündən sonra rotasiya tövsiyə olunur; məhsul xatırlatma göstərir, lakin rotasiya edilmədiyi üçün heç vaxt abunəliyi söndürmür.
Rotasiya üst-üstə düşmə pəncərəsindən istifadə edir: POST /api/v1/plugins/{id}/webhook-secret/rotate sonrası həm köhnə, həm yeni açar yeddi gün ərzində yoxlamadan keçir, yeni çatdırılmalar yenisi ilə imzalanır, köhnəsi isə pəncərədən sonra silinir. Rotasiya etdiyiniz an heç nə pozulmur.
Gizli açar sızarsa, POST /api/v1/plugins/{id}/webhook-secret/revoke onu dərhal etibarsız edir, yenisini verir, hesab adminlərinə e-poçt göndərir və audit qeydi yazır.

Təkrar cəhdlər və dead letter-lər

2xx olmayan cavab və ya şəbəkə uğursuzluğu təkrar cəhdi planlaşdırır:

Cəhd	Əvvəlkindən sonrakı gecikmə
1	dərhal
2	15 saniyə
3	1 dəqiqə
4	5 dəqiqə
5	30 dəqiqə
6	2 saat
7	8 saat
8	24 saat

408, 429, 5xx və şəbəkə xətaları təkrarlanır. 400, 401, 403, 404 və 410 təkrarlanmır: çatdırılma birbaşa dead-letter növbəsinə düşür, çünki rədd edilmiş imzanı və ya mövcud olmayan endpoint-i təkrarlamaq kömək edə bilməz. Səkkiz uğursuz cəhddən sonra çatdırılma da dead-letter növbəsinə düşür.

Dead letter-lər 30 gün saxlanılır və Parametrlər → Plaginlər → {plugin} → Webhook jurnalı → DLQ bölməsində görünür; orada admin onlardan birini yenidən göndərə bilər (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limitlər

Gedən gövdə: standart olaraq 1 MB (hər plagin üçün tənzimlənir). RolChat-ə daxil olan gövdə: 5 MB. Daha böyüyü 413 alır.
Plagin allowed_source_ips elan edə bilər; RolChat bu icazə siyahısını yoxlamadan əvvəl tətbiq edir.
Əlavə məntiqi yoxlama kimi RolChat-Webhook/1.0 user agent-ini yoxlaya bilərsiniz. Bu, təhlükəsizlik tədbiri deyil.

RolChat-ə daxil olan webhook-lar

Provayderlər öz imza sxemlərindən (Twilio, Telnyx, Bandwidth, WhatsApp üçün Meta, Stripe) istifadə edərək RolChat-ə /api/v1/webhooks/{category}/{adapter} ünvanına göndərir. Hər adapter öz provayderinin imzasını yoxlayır, payload-u normallaşdırır və onu RolChat imzası ilə daxili hadisə şinində yenidən dərc edir. Öz sisteminiz yuxarıda təsvir olunan eyni X-RolChat-* başlıqları ilə, endpoint-in aid olduğu plaginin gizli açarı ilə imzalayaraq RolChat-ə göndərə bilər.

Avtomatlaşdırma üçün webhooklar

Avtomatlaşdırma modulunun HTTP sorğusu göndər əməliyyatının öz çatdırılma qaydaları var:

Hər hesab üçün bir məxfi açar. Onu Avtomatlaşdırma ekranında göstərin və ya dəyişdirin (Owner və Admin). Dəyişdirmə dərhal qüvvəyə minir: üst-üstə düşmə pəncərəsi yoxdur, köhnə açar dərhal yoxlanmağı dayandırır, ona görə əvvəlcə qəbuledicinizi yeniləyin və ya qısa fasilə ilə razılaşın.
Gözləmə müddəti: RolChat cavabı 10 saniyə gözləyir.
Təkrar cəhdlər: cəmi 6 cəhdə qədər. 2-ci cəhddən əvvəl fasilə 30 saniyədir, sonra təxminən 2 dəqiqə, 8 dəqiqə, 32 dəqiqə və 2 saat 8 dəqiqə; hər biri 20 %-ə qədər dəyişir. Tək fasilə heç vaxt 6 saatı keçmir.
Nə təkrarlanır: şəbəkə xətaları, taym-autlar, 5xx, 408, 425 və 429. Digər 4xx cavabları, bloklanmış ünvan və ya həddindən artıq böyük gövdə təkrarlanmır: çatdırılma son uğursuz cəhddən sonrakı kimi birbaşa dead-letter növbəsinə düşür.
Başlıqlar: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Qəbuledicinizin sınaqdan keçirilməsi

POST /api/v1/webhooks/test-signature çağıran plaginin endpoint-inə sintetik imzalı hadisə göndərir ki, real trafik gəlməzdən əvvəl implementasiyanızı başdan sona yoxlaya biləsiniz.

Tipik səhvlər

Xam baytlar əvəzinə təhlil edilib yenidən kodlaşdırılmış JSON-a qarşı yoxlama aparmaq.
İmzaları müqayisə etmək üçün == istifadə etmək.
Dublikatları hadisə ID-si əvəzinə nonce üzrə aradan qaldırmaq (hər təkrar cəhdin yeni nonce-u var).
Beş dəqiqədən çox fərqlənən saat.
Cavab verməzdən əvvəl yavaş iş görmək, sonra 15 saniyədə taym-aut almaq və eyni hadisəni yenidən qəbul etmək.