Mga webhook

Inihahatid ng RolChat ang mga event sa mga system mo bilang mga naka-sign na HTTP request na POST. Inilalarawan ng pahinang ito ang mga webhook ng plugin; iba ang mga webhook na ipinapadala ng isang Automation rule sa mga retry, oras ng paghihintay at pag-rotate ng secret, tingnan ang Mga automation webhook. Parehong mga patakaran ang nalalapat sa kabilang direksyon kapag nagpo-post sa RolChat ang system mo, isang plugin o isang provider. I-verify ang bawat delivery ayon sa pagkakasunod-sunod sa ibaba bago ka kumilos dito.

Ano ang itsura ng delivery

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	Kahulugan
`X-RolChat-Timestamp`	Unix seconds sa oras ng pagpapadala. Bahagi ng naka-sign na mensahe.
`X-RolChat-Signature`	`sha256=<hex>`. Pinapangalanan ng prefix ang algorithm para mapalitan ito sa hinaharap.
`X-RolChat-Nonce`	ULID na natatangi sa HTTP request na ito. Nakakakuha ng bagong nonce ang retry.
`X-RolChat-Event-Id`	Sariling ID ng event. Hindi nagbabago sa mga retry; gamitin ito para mag-deduplicate.

Sa mga HTTPS endpoint lang napupunta ang mga palabas na delivery. Tinatanggihan ang HTTP URL kapag ginagawa ang subscription.

Ang signature

Ang naka-sign na mensahe ay ang timestamp, isang literal na tuldok, at ang raw request body, byte por byte:

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

I-sign ang mga byte na natanggap mo, hindi ang muling na-serialise na kopya ng na-parse na JSON. Sinisira ng mga pagbabago sa whitespace o pagkakasunod-sunod ng key ang signature. SHA-256 lang ang tinatanggap na algorithm.

Ang mga request na ipinapadala ng HTTP action ng module na Automation ay nilalagdaan gamit ang dalawang header. Ang X-RolChat-Signature ay sha256= kasama ang HMAC-SHA256 ng body lang. Ang X-RolChat-Signature-V2 ay ang HMAC-SHA256 ng <timestamp>.<body>, ang scheme na inilarawan sa itaas, na ang X-RolChat-Timestamp ang timestamp. I-verify ang V2 header; hindi pinoprotektahan ng header na body lang laban sa na-replay na request. Walang X-RolChat-Nonce at X-RolChat-Event-Id ang mga request na ito; ang bawat pagsubok ng iisang delivery ay may parehong X-RolChat-Delivery-Id at sarili nitong numero sa X-RolChat-Attempt, kaya laktawan ang nonce check at mag-deduplicate gamit ang X-RolChat-Delivery-Id. Binabasa ng mga verification sample ang X-RolChat-Signature: para sa mga automation request, basahin na lang ang X-RolChat-Signature-V2.

Pag-verify ng delivery

Gawin ang limang check na ito nang sunud-sunod. Nasa pahinang mga sample ng pag-verify ang mga sample sa Python, Node.js, Go, Ruby at PHP.

Pagiging bago. Tanggihan kung |now − X-RolChat-Timestamp| > 300 segundo (400). Kaya ng limang minuto ang clock skew at ginagawa nitong walang silbi pagkatapos noon ang nahuling request. Panatilihin sa NTP ang server mo.
Signature. Kalkulahin ang inaasahang value at ikumpara gamit ang constant-time na paghahambing (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Tanggihan nang may 401 kapag hindi tugma. Naglalantad ng timing ang simpleng paghahambing ng string at hindi ito katanggap-tanggap.
Nonce. Iimbak ang X-RolChat-Nonce na may TTL na 10 minuto gamit ang atomic na set-if-absent (SET NX EX 600). Kung umiiral na ito, tanggihan nang may 409: replay ang request. Kung down ang nonce store mo, mag-fail closed nang may 503 para mag-retry ang RolChat; huwag kailanman bumagsak sa “tanggapin”.
I-parse ang body ngayon lang.
Mag-deduplicate ayon sa event ID. May dalang bagong nonce ang mga retry pero parehong X-RolChat-Event-Id. Kung naproseso mo na ang ID na iyon sa nakaraang pitong araw, sumagot ng 200 nang hindi muling pinoproseso.

Sumagot ng 2xx sa sandaling ligtas nang natanggap ang delivery; gawin ang trabaho nang asynchronous. Naghihintay ang RolChat nang 15 segundo para sa sagot.

Mga secret

Ang webhook secret ay 64 na random na byte, naka-encode sa base64url (mga 86 character). Nabubuo ito kapag ginawa ang subscription o plugin at isang beses lang ipinapakita.
Iimbak ito sa sarili mong vault o environment; naka-encrypt na kopya lang ang itinatabi ng RolChat.
Inirerekomenda ang rotation pagkatapos ng 90 araw; nagpapakita ng paalala ang produkto pero hindi kailanman dini-disable ang subscription dahil hindi nag-rotate.
Gumagamit ang rotation ng overlap window: pagkatapos ng POST /api/v1/plugins/{id}/webhook-secret/rotate, parehong nagve-verify ang luma at bagong secret nang pitong araw, naka-sign sa bago ang mga bagong delivery, at binubura ang luma pagkatapos ng window. Walang nasisira sa sandaling mag-rotate ka.
Kung nag-leak ang secret, agad itong pinapawalang-bisa ng POST /api/v1/plugins/{id}/webhook-secret/revoke, nagbibigay ng bago, nag-e-e-mail sa mga admin ng account at nagsusulat ng entry sa audit.

Mga retry at dead letter

Nag-iiskedyul ng retry ang sagot na hindi 2xx o ang pagkabigo sa network:

Pagtatangka	Pagitan mula sa nauna
1	agad
2	15 segundo
3	1 minuto
4	5 minuto
5	30 minuto
6	2 oras
7	8 oras
8	24 oras

Nire-retry ang 408, 429, 5xx at mga error sa network. Hindi ang 400, 401, 403, 404 at 410: diretso sa dead-letter queue ang delivery, dahil hindi makakatulong ang pag-retry sa tinanggihang signature o nawawalang endpoint. Pagkatapos ng walong bigong pagtatangka, napupunta rin sa dead letter ang delivery.

Itinatabi ang mga dead letter nang 30 araw at nakikita ang mga ito sa Mga Setting → Mga Plugin → {plugin} → Webhook log → DLQ, kung saan puwedeng i-replay ng admin ang isa (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Mga limitasyon

Palabas na body: 1 MB bilang default (nako-configure kada plugin). Papasok na body sa RolChat: 5 MB. Kapag mas malaki, 413.
Puwedeng magdeklara ang plugin ng allowed_source_ips; inilalapat ng RolChat ang allowlist na iyon bago mag-verify.
Puwede kang mag-pin sa user agent na RolChat-Webhook/1.0 bilang dagdag na sanity check. Hindi ito kontrol sa seguridad.

Mga papasok na webhook sa RolChat

Nagpo-post ang mga provider sa RolChat sa /api/v1/webhooks/{category}/{adapter} gamit ang sarili nilang mga signature scheme (Twilio, Telnyx, Bandwidth, Meta para sa WhatsApp, Stripe). Bine-verify ng bawat adapter ang signature ng provider nito, ginagawang normal ang payload at muling ina-publish ito sa internal na event bus na may signature ng RolChat. Makakapag-post ang sarili mong system sa RolChat gamit ang parehong mga header na X-RolChat-* na inilarawan sa itaas, naka-sign sa secret ng plugin na may-ari ng endpoint.

Mga automation webhook

May sariling mga patakaran sa delivery ang action na Magpadala ng HTTP request ng module na Automation:

Isang secret kada account. Ipakita o i-rotate ito sa screen ng Automation (Owner at Admin). Agad na epektibo ang rotation: walang overlap window, agad na hindi na nave-verify ang lumang secret, kaya i-update muna ang receiver mo o tanggapin ang maikling puwang.
Oras ng paghihintay: naghihintay ang RolChat ng 10 segundo para sa sagot.
Mga retry: hanggang 6 na pagsubok sa kabuuan. Ang pahinga bago ang pagsubok 2 ay 30 segundo, pagkatapos mga 2 minuto, 8 minuto, 32 minuto at 2 oras 8 minuto, bawat isa ay may pagkakaiba hanggang 20 %. Hindi kailanman lalampas sa 6 na oras ang isang pahinga.
Ano ang ire-retry: mga network error, timeout, 5xx, 408, 425 at 429. Hindi ire-retry ang ibang sagot na 4xx, naka-block na address o sobrang laking body: diretso sa dead-letter queue ang delivery, tulad pagkatapos ng huling pumalyang pagsubok.
Mga header: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Pagsubok sa receiver mo

Nagpapadala ang POST /api/v1/webhooks/test-signature ng synthetic na naka-sign na event sa endpoint ng tumatawag na plugin para ma-verify mo ang implementasyon mo mula simula hanggang dulo bago dumating ang tunay na traffic.

Mga karaniwang pagkakamali

Pag-verify laban sa na-parse at muling na-encode na JSON sa halip na sa mga raw byte.
Paggamit ng == para ikumpara ang mga signature.
Pag-deduplicate ayon sa nonce (may bago ang bawat retry) sa halip na ayon sa event ID.
Orasang lihis nang higit sa limang minuto.
Paggawa ng mabagal na trabaho bago sumagot, tapos nagta-time out sa 15 segundo at natatanggap ulit ang parehong event.