Webhookit

RolChat toimittaa tapahtumat järjestelmiisi allekirjoitettuina HTTP POST -pyyntöinä. Tämä sivu kuvaa laajennusten webhookit; Automaatio-säännön lähettämät webhookit eroavat uusintayrityksissä, odotusajassa ja salaisuuden vaihdossa, katso Automaation webhookit. Samat säännöt pätevät toiseen suuntaan, kun järjestelmäsi, laajennus tai palveluntarjoaja lähettää tietoja RolChatiin. Tarkista jokainen toimitus alla olevassa järjestyksessä ennen kuin toimit sen perusteella.

Miltä toimitus näyttää

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

Otsake	Merkitys
`X-RolChat-Timestamp`	Unix-sekunnit lähetyshetkellä. Osa allekirjoitettua viestiä.
`X-RolChat-Signature`	`sha256=<hex>`. Etuliite nimeää algoritmin, jotta sitä voidaan myöhemmin muuttaa.
`X-RolChat-Nonce`	Tälle HTTP-pyynnölle yksilöllinen ULID. Uusintayritys saa uuden noncen.
`X-RolChat-Event-Id`	Tapahtuman oma tunniste. Pysyy samana uusintayrityksissä; käytä sitä kaksoiskappaleiden poistoon.

Lähtevät toimitukset menevät vain HTTPS-päätepisteisiin. HTTP-osoite hylätään tilausta luotaessa.

Allekirjoitus

Allekirjoitettu viesti on aikaleima, kirjaimellinen piste ja pyynnön raaka runko tavu tavulta:

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

Allekirjoita vastaanottamasi tavut, älä jäsennetyn JSONin uudelleen sarjallistettua kopiota. Välilyöntien tai avainten järjestyksen muutokset rikkovat allekirjoituksen. SHA-256 on ainoa hyväksytty algoritmi.

Automaatio-moduulin HTTP-toiminnon lähettämät pyynnöt allekirjoitetaan kahdella otsakkeella. X-RolChat-Signature on sha256= ja pelkän rungon HMAC-SHA256. X-RolChat-Signature-V2 on <timestamp>.<body>-merkkijonon HMAC-SHA256, eli yllä kuvattu malli, aikaleimana X-RolChat-Timestamp. Tarkista V2-otsake; pelkkään runkoon perustuva otsake ei suojaa toistohyökkäykseltä. Näissä pyynnöissä ei ole X-RolChat-Nonce- eikä X-RolChat-Event-Id-otsaketta; yhden toimituksen jokaisessa yrityksessä on sama X-RolChat-Delivery-Id ja oma numeronsa otsakkeessa X-RolChat-Attempt, joten ohita nonce-tarkistus ja poista kaksoiskappaleet X-RolChat-Delivery-Id:n perusteella. Tarkistusesimerkit lukevat X-RolChat-Signature: automaatiopyynnöissä lue sen sijaan X-RolChat-Signature-V2.

Toimituksen tarkistaminen

Tee nämä viisi tarkistusta järjestyksessä. Esimerkit Pythonilla, Node.js:llä, Golla, Rubylla ja PHP:llä ovat sivulla Tarkistusesimerkit.

Tuoreus. Hylkää, jos |now − X-RolChat-Timestamp| > 300 sekuntia (400). Viisi minuuttia sietää kellojen eron ja tekee siepatusta pyynnöstä arvottoman sen jälkeen. Pidä palvelimesi NTP:n piirissä.
Allekirjoitus. Laske odotettu arvo ja vertaa sitä vakioaikaisella vertailulla (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Hylkää koodilla 401, jos arvot eivät täsmää. Tavallinen merkkijonovertailu vuotaa ajoitustietoa, eikä se ole hyväksyttävää.
Nonce. Tallenna X-RolChat-Nonce 10 minuutin TTL:llä atomisella set-if-absent-operaatiolla (SET NX EX 600). Jos se on jo olemassa, hylkää koodilla 409: pyyntö on toisto. Jos nonce-varastosi ei ole käytettävissä, epäonnistu suljetusti koodilla 503, jotta RolChat yrittää uudelleen; älä koskaan päädy “hyväksy”-haaraan.
Jäsennä runko vasta nyt.
Poista kaksoiskappaleet tapahtuman tunnisteen perusteella. Uusintayrityksillä on uusi nonce mutta sama X-RolChat-Event-Id. Jos olet käsitellyt kyseisen tunnisteen viimeisten seitsemän päivän aikana, vastaa 200 käsittelemättä uudelleen.

Vastaa 2xx heti, kun toimitus on turvallisesti vastaanotettu; tee varsinainen työ asynkronisesti. RolChat odottaa vastausta 15 sekuntia.

Salaisuudet

Webhookin salaisuus on 64 satunnaista tavua base64url-koodattuna (noin 86 merkkiä). Se luodaan, kun tilaus tai laajennus luodaan, ja näytetään kerran.
Säilytä se omassa holvissasi tai ympäristömuuttujissa; RolChat säilyttää vain salatun kopion.
Kierrätystä suositellaan 90 päivän jälkeen; tuote näyttää muistutuksen mutta ei koskaan poista tilausta käytöstä kierrättämättä jättämisen vuoksi.
Kierrätys käyttää päällekkäisyysikkunaa: kutsun POST /api/v1/plugins/{id}/webhook-secret/rotate jälkeen sekä vanha että uusi salaisuus kelpaavat seitsemän päivän ajan, uudet toimitukset allekirjoitetaan uudella, ja vanha poistetaan ikkunan jälkeen. Mikään ei rikkoudu kierrätyshetkellä.
Jos salaisuus vuotaa, POST /api/v1/plugins/{id}/webhook-secret/revoke mitätöi sen välittömästi, myöntää uuden, lähettää sähköpostin tilin ylläpitäjille ja kirjoittaa tarkastuslokimerkinnän.

Uusintayritykset ja kuolleet kirjeet

Muu kuin 2xx-vastaus tai verkkovirhe ajastaa uusintayrityksen:

Yritys	Viive edellisestä
1	heti
2	15 sekuntia
3	1 minuutti
4	5 minuuttia
5	30 minuuttia
6	2 tuntia
7	8 tuntia
8	24 tuntia

408, 429, 5xx ja verkkovirheet yritetään uudelleen. 400, 401, 403, 404 ja 410 eivät: toimitus menee suoraan kuolleiden kirjeiden jonoon (DLQ), koska hylätyn allekirjoituksen tai puuttuvan päätepisteen uudelleenyrittäminen ei voi auttaa. Kahdeksan epäonnistuneen yrityksen jälkeen myös toimitus siirretään kuolleiden kirjeiden jonoon.

Kuolleet kirjeet säilytetään 30 päivää, ja ne näkyvät kohdassa Asetukset → Laajennukset → {plugin} → Webhook-loki → DLQ, jossa ylläpitäjä voi toistaa yksittäisen toimituksen (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Rajat

Lähtevä runko: oletuksena 1 Mt (määritettävissä laajennuskohtaisesti). RolChatiin saapuva runko: 5 Mt. Suurempi on 413.
Laajennus voi ilmoittaa allowed_source_ips; RolChat soveltaa tätä sallittujen luetteloa ennen tarkistusta.
Voit lisäksi tarkistaa RolChat-Webhook/1.0-käyttäjäagentin ylimääräisenä järkevyystarkistuksena. Se ei ole tietoturvakontrolli.

Saapuvat webhookit RolChatiin

Palveluntarjoajat lähettävät RolChatiin osoitteeseen /api/v1/webhooks/{category}/{adapter} omilla allekirjoitusmenetelmillään (Twilio, Telnyx, Bandwidth, Meta WhatsAppille, Stripe). Jokainen adapteri tarkistaa palveluntarjoajansa allekirjoituksen, normalisoi hyötykuorman ja julkaisee sen uudelleen sisäisellä tapahtumaväylällä RolChatin allekirjoituksella. Oma järjestelmäsi voi lähettää RolChatiin samoilla yllä kuvatuilla X-RolChat-*-otsakkeilla, jotka on allekirjoitettu päätepisteen omistavan laajennuksen salaisuudella.

Automaation webhookit

Lähetä HTTP-pyyntö -toiminnolla Automaatio-moduulissa on omat toimityssäännöt:

Yksi salaisuus tiliä kohden. Näytä tai vaihda se Automaatio-näkymässä (omistaja ja ylläpitäjä). Vaihto tulee voimaan heti: päällekkäisyysikkunaa ei ole, vanha salaisuus lakkaa toimimasta välittömästi, joten päivitä ensin vastaanottimesi tai hyväksy lyhyt katko.
Odotusaika: RolChat odottaa vastausta 10 sekuntia.
Uusintayritykset: enintään 6 yritystä yhteensä. Tauko ennen yritystä 2 on 30 sekuntia, sen jälkeen noin 2 minuuttia, 8 minuuttia, 32 minuuttia ja 2 tuntia 8 minuuttia, kukin enintään 20 % vaihdellen. Yksittäinen tauko ei koskaan ylitä 6 tuntia.
Mitä yritetään uudelleen: verkkovirheet, aikakatkaisut, 5xx, 408, 425 ja 429. Muita 4xx-vastauksia, estettyä osoitetta tai liian suurta bodya ei yritetä uudelleen: toimitus menee suoraan kuolleiden kirjeiden jonoon, kuten viimeisen epäonnistuneen yrityksen jälkeenkin.
Otsakkeet: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Vastaanottimen testaaminen

POST /api/v1/webhooks/test-signature lähettää synteettisen allekirjoitetun tapahtuman kutsuvan laajennuksen päätepisteeseen, jotta voit tarkistaa toteutuksesi päästä päähän ennen todellisen liikenteen saapumista.

Yleisiä virheitä

Tarkistus jäsennettyä ja uudelleen koodattua JSONia vasten raakojen tavujen sijaan.
Allekirjoitusten vertailu ==-operaattorilla.
Kaksoiskappaleiden poisto noncen perusteella (jokaisella uusintayrityksellä on uusi) tapahtuman tunnisteen sijaan.
Kello, joka on yli viisi minuuttia väärässä.
Hidas työ ennen vastaamista, jolloin aikakatkaisu tulee 15 sekunnissa ja sama tapahtuma saapuu uudelleen.