Вебхуктар

RolChat оқиғаларды жүйелеріңізге қол қойылған HTTP POST сұраулары ретінде жеткізеді. Бұл бет плагин вебхуктарын сипаттайды; Автоматтандыру ережесі жіберетін вебхуктар қайталаулар, күту уақыты және құпияны ауыстыру жағынан ерекшеленеді, Автоматтандыру вебхуктары бөлімін қараңыз. Жүйеңіз, плагин немесе провайдер RolChat-қа жібергенде кері бағытта да сол ережелер қолданылады. Әр жеткізілім бойынша әрекет етпес бұрын оны төмендегі ретпен тексеріңіз.

Жеткізілім қандай болады

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

Тақырып	Мағынасы
`X-RolChat-Timestamp`	Жіберу сәтіндегі Unix секундтары. Қол қойылған хабарламаның бөлігі.
`X-RolChat-Signature`	`sha256=<hex>`. Префикс кейін өзгерту үшін алгоритмді атайды.
`X-RolChat-Nonce`	Осы HTTP сұрауына бірегей ULID. Қайталауға жаңа nonce беріледі.
`X-RolChat-Event-Id`	Оқиғаның өз ID-і. Қайталаулар кезінде өзгермейді; қайталанатындарды алып тастау үшін пайдаланыңыз.

Шығыс жеткізілімдер тек HTTPS эндпоинттеріне жіберіледі. HTTP URL жазылым жасалған кезде қабылданбайды.

Қолтаңба

Қол қойылатын хабарлама - уақыт белгісі, нүкте таңбасы және сұраудың өңделмеген денесі, байтпа-байт:

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

JSON-ды талдап, қайта сериализацияланған көшірмеге емес, өзіңіз алған байттарға қол қойыңыз. Бос орындардың немесе кілттер ретінің өзгеруі қолтаңбаны бұзады. SHA-256 - қабылданатын жалғыз алгоритм.

Автоматтандыру модулінің HTTP әрекеті жіберетін сұрауларға екі тақырыппен қол қойылады. X-RolChat-Signature - sha256= және тек денеден алынған HMAC-SHA256. X-RolChat-Signature-V2 - <timestamp>.<body> мәнінен алынған HMAC-SHA256, яғни жоғарыда сипатталған схема, ал timestamp ретінде X-RolChat-Timestamp алынады. V2 тақырыбын тексеріңіз; тек денеге арналған тақырып қайта жіберілген сұраудан қорғамайды. Бұл сұрауларда X-RolChat-Nonce та, X-RolChat-Event-Id та жоқ; бір жеткізілімнің барлық әрекеттерінде бірдей X-RolChat-Delivery-Id және X-RolChat-Attempt ішінде өз нөмірі болады, сондықтан nonce тексеруін өткізіп жіберіңіз де, қайталануларды X-RolChat-Delivery-Id бойынша алып тастаңыз. Тексеру мысалдары X-RolChat-Signature оқиды: автоматтандыру сұрауларында оның орнына X-RolChat-Signature-V2 оқыңыз.

Жеткізілімді тексеру

Мына бес тексерісті ретімен орындаңыз. Python, Node.js, Go, Ruby және PHP тілдеріндегі мысалдар тексеру мысалдары бетінде.

Жаңалық. |now − X-RolChat-Timestamp| > 300 секунд болса, қабылдамаңыз (400). Бес минут сағаттардың ауытқуына шыдайды және одан кейін ұсталған сұрауды пайдасыз етеді. Серверіңізді NTP арқылы синхрондап ұстаңыз.
Қолтаңба. Күтілетін мәнді есептеп, тұрақты уақыттағы салыстырумен (hmac.compare_digest, crypto.timingSafeEqual, hash_equals) салыстырыңыз. Сәйкес келмесе, 401 деп қабылдамаңыз. Жолдарды қарапайым салыстыру уақыт арқылы ақпарат таратады және жарамайды.
Nonce. X-RolChat-Nonce мәнін атомдық «жоқ болса орнату» (SET NX EX 600) арқылы 10 минуттық TTL-мен сақтаңыз. Ол бұрыннан бар болса, 409 деп қабылдамаңыз: бұл қайта жіберілген сұрау. Nonce қоймасы істемей тұрса, RolChat қайталауы үшін 503 деп қауіпсіз түрде бас тартыңыз; ешқашан «қабылдау» нұсқасына өтпеңіз.
Денені тек енді талдаңыз.
Оқиға ID-і бойынша қайталанатындарды алып тастаңыз. Қайталауларда жаңа nonce болады, бірақ X-RolChat-Event-Id сол күйі қалады. Бұл ID-ді соңғы жеті күнде өңдеген болсаңыз, қайта өңдемей 200 деп жауап беріңіз.

Жеткізілім қауіпсіз қабылданған бойда 2xx деп жауап беріңіз; жұмысты асинхронды орындаңыз. RolChat жауапты 15 секунд күтеді.

Құпиялар

Вебхук құпиясы - base64url түрінде кодталған 64 кездейсоқ байт (шамамен 86 таңба). Ол жазылым немесе плагин жасалғанда генерацияланып, бір рет көрсетіледі.
Оны өз қоймаңызда немесе ортада сақтаңыз; RolChat тек шифрланған көшірмесін сақтайды.
90 күннен кейін ауыстыру ұсынылады; өнім еске салғыш көрсетеді, бірақ ауыстырмағаныңыз үшін жазылымды ешқашан өшірмейді.
Ауыстыру қабаттасу кезеңін пайдаланады: POST /api/v1/plugins/{id}/webhook-secret/rotate шақырылғаннан кейін ескі де, жаңа да құпия жеті күн бойы тексеруден өтеді, жаңа жеткізілімдерге жаңасымен қол қойылады, ал ескісі кезең аяқталғаннан кейін жойылады. Ауыстырған сәтте ештеңе бұзылмайды.
Құпия жария болып қалса, POST /api/v1/plugins/{id}/webhook-secret/revoke оны дереу жарамсыз етеді, жаңасын береді, аккаунт әкімшілеріне электрондық хат жібереді және аудит жазбасын жасайды.

Қайталаулар және жеткізілмеген хабарламалар

2xx емес жауап немесе желі ақауы қайталауды жоспарлайды:

Әрекет	Алдыңғысынан кейінгі кідіріс
1	дереу
2	15 секунд
3	1 минут
4	5 минут
5	30 минут
6	2 сағат
7	8 сағат
8	24 сағат

408, 429, 5xx және желі қателері қайталанады. 400, 401, 403, 404 және 410 қайталанбайды: жеткізілім бірден жеткізілмеген хабарламалар кезегіне түседі, өйткені қабылданбаған қолтаңбаны немесе жоқ эндпоинтті қайталау көмектеспейді. Сегіз сәтсіз әрекеттен кейін де жеткізілім жеткізілмегендер кезегіне түседі.

Жеткізілмеген хабарламалар 30 күн сақталады және Баптаулар → Плагиндер → {plugin} → Вебхук журналы → DLQ бөлімінде көрінеді, онда әкімші біреуін қайта жібере алады (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Лимиттер

Шығыс дене: әдепкі бойынша 1 MB (әр плагин үшін бапталады). RolChat-қа кіріс дене: 5 MB. Үлкенірегі 413 қайтарады.
Плагин allowed_source_ips жариялай алады; RolChat бұл рұқсат тізімін тексеруден бұрын қолданады.
Қосымша тексеріс ретінде RolChat-Webhook/1.0 пайдаланушы агентіне сүйенуге болады. Бұл қауіпсіздік шарасы емес.

RolChat-қа кіріс вебхуктар

Провайдерлер RolChat-қа /api/v1/webhooks/{category}/{adapter} мекенжайы бойынша өз қол қою схемаларын (Twilio, Telnyx, Bandwidth, WhatsApp үшін Meta, Stripe) пайдаланып жібереді. Әр адаптер өз провайдерінің қолтаңбасын тексеріп, деректерді қалыпқа келтіреді және оларды RolChat қолтаңбасымен ішкі оқиғалар шинасына қайта жариялайды. Сіздің жүйеңіз RolChat-қа жоғарыда сипатталған X-RolChat-* тақырыптарымен, эндпоинт тиесілі плагиннің құпиясымен қол қойып жібере алады.

Автоматтандыру вебхуктары

Автоматтандыру модулінің HTTP сұрауын жіберу әрекетінің жеткізудің өз ережелері бар:

Аккаунтқа бір құпия. Оны Автоматтандыру экранында көрсетуге немесе ауыстыруға болады (Owner және Admin). Ауыстыру бірден күшіне енеді: қабаттасу терезесі жоқ, ескі құпия бірден тексерілуін тоқтатады, сондықтан алдымен қабылдағышыңызды жаңартыңыз немесе қысқа үзілісті қабылдаңыз.
Күту уақыты: RolChat жауапты 10 секунд күтеді.
Қайталаулар: барлығы 6 әрекетке дейін. 2-әрекеттің алдындағы үзіліс - 30 секунд, одан кейін шамамен 2 минут, 8 минут, 32 минут және 2 сағат 8 минут, әрқайсысы 20 %-ға дейін ауытқиды. Бір үзіліс ешқашан 6 сағаттан аспайды.
Не қайталанады: желі қателері, күту уақытының аяқталуы, 5xx, 408, 425 және 429. Басқа 4xx жауаптары, бұғатталған мекенжай немесе тым үлкен дене қайталанбайды: жеткізілім соңғы сәтсіз әрекеттен кейін сияқты тікелей жеткізілмеген хабарламалар кезегіне түседі.
Тақырыптар: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Қабылдағышыңызды тестілеу

POST /api/v1/webhooks/test-signature шақырушы плагиннің эндпоинтіне синтетикалық қол қойылған оқиға жібереді, сондықтан нақты трафик келмей тұрып іске асыруыңызды басынан аяғына дейін тексере аласыз.

Жиі кездесетін қателер

Өңделмеген байттардың орнына талданып, қайта кодталған JSON бойынша тексеру.
Қолтаңбаларды салыстыру үшін == пайдалану.
Қайталанатындарды оқиға ID-і бойынша емес, nonce бойынша алып тастау (әр қайталауда жаңа nonce болады).
Бес минуттан көп ауытқитын сағат.
Жауап бермес бұрын баяу жұмыс орындап, 15 секундта күту уақыты өтіп кетуі және сол оқиғаны қайта алу.