Webhook

RolChat mengirim event ke sistem Anda sebagai permintaan HTTP POST yang ditandatangani. Halaman ini menjelaskan webhook plugin; webhook yang dikirim oleh aturan Otomasi berbeda dalam percobaan ulang, waktu tunggu, dan rotasi secret, lihat Webhook otomasi. Aturan yang sama berlaku ke arah sebaliknya, saat sistem Anda, plugin, atau penyedia mengirim data ke RolChat. Verifikasi setiap pengiriman sesuai urutan di bawah sebelum Anda menindaklanjutinya.

Seperti apa sebuah pengiriman

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	Arti
`X-RolChat-Timestamp`	Detik Unix saat pengiriman. Bagian dari pesan yang ditandatangani.
`X-RolChat-Signature`	`sha256=<hex>`. Prefiks menyebut algoritmanya agar dapat diubah nanti.
`X-RolChat-Nonce`	ULID yang unik untuk permintaan HTTP ini. Percobaan ulang mendapat nonce baru.
`X-RolChat-Event-Id`	ID event itu sendiri. Tetap sama di setiap percobaan ulang; gunakan untuk deduplikasi.

Pengiriman keluar hanya ke endpoint HTTPS. URL HTTP ditolak saat langganan dibuat.

Tanda tangan

Pesan yang ditandatangani adalah stempel waktu, sebuah titik literal, dan body permintaan mentah, byte demi byte:

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

Tandatangani byte yang Anda terima, bukan salinan JSON yang sudah di-parse lalu diserialisasi ulang. Perubahan spasi atau urutan kunci merusak tanda tangan. SHA-256 adalah satu-satunya algoritma yang diterima.

Permintaan yang dikirim oleh aksi HTTP modul Otomasi ditandatangani dengan dua header. X-RolChat-Signature adalah sha256= ditambah HMAC-SHA256 dari body saja. X-RolChat-Signature-V2 adalah HMAC-SHA256 dari <timestamp>.<body>, yaitu skema yang dijelaskan di atas, dengan X-RolChat-Timestamp sebagai timestamp. Verifikasi header V2; header body-saja tidak melindungi dari permintaan yang diputar ulang. Permintaan ini tidak membawa X-RolChat-Nonce dan X-RolChat-Event-Id; setiap percobaan dari satu pengiriman membawa X-RolChat-Delivery-Id yang sama dan nomornya sendiri di X-RolChat-Attempt, jadi lewati pemeriksaan nonce dan lakukan deduplikasi berdasarkan X-RolChat-Delivery-Id. Contoh verifikasi membaca X-RolChat-Signature: untuk permintaan otomasi, baca X-RolChat-Signature-V2 sebagai gantinya.

Memverifikasi pengiriman

Lakukan lima pemeriksaan ini secara berurutan. Contoh dalam Python, Node.js, Go, Ruby, dan PHP ada di halaman contoh verifikasi.

Kesegaran. Tolak jika |now − X-RolChat-Timestamp| > 300 detik (400). Lima menit menoleransi selisih jam dan membuat permintaan yang disadap tidak berguna setelahnya. Jaga server Anda tetap tersinkron dengan NTP.
Tanda tangan. Hitung nilai yang diharapkan dan bandingkan dengan perbandingan waktu konstan (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Tolak dengan 401 jika tidak cocok. Perbandingan string biasa membocorkan informasi waktu dan tidak dapat diterima.
Nonce. Simpan X-RolChat-Nonce dengan TTL 10 menit menggunakan set-if-absent atomik (SET NX EX 600). Jika sudah ada, tolak dengan 409: permintaan tersebut adalah replay. Jika penyimpanan nonce Anda mati, gagal secara aman dengan 503 agar RolChat mencoba ulang; jangan pernah jatuh ke “terima”.
Parse body baru sekarang.
Deduplikasi berdasarkan ID event. Percobaan ulang membawa nonce baru tetapi X-RolChat-Event-Id yang sama. Jika Anda sudah memproses ID tersebut dalam tujuh hari terakhir, jawab 200 tanpa memproses lagi.

Jawab 2xx segera setelah pengiriman diterima dengan aman; kerjakan prosesnya secara asinkron. RolChat menunggu respons selama 15 detik.

Secret

Secret webhook adalah 64 byte acak yang dienkode base64url (sekitar 86 karakter). Secret dibuat saat langganan atau plugin dibuat dan ditampilkan sekali.
Simpan di vault atau environment Anda sendiri; RolChat hanya menyimpan salinan terenkripsi.
Rotasi disarankan setelah 90 hari; produk menampilkan pengingat tetapi tidak pernah menonaktifkan langganan karena tidak dirotasi.
Rotasi menggunakan jendela tumpang tindih: setelah POST /api/v1/plugins/{id}/webhook-secret/rotate, secret lama dan baru sama-sama lolos verifikasi selama tujuh hari, pengiriman baru ditandatangani dengan secret baru, dan secret lama dihapus setelah jendela berakhir. Tidak ada yang rusak saat Anda merotasi.
Jika secret bocor, POST /api/v1/plugins/{id}/webhook-secret/revoke langsung membatalkannya, menerbitkan yang baru, mengirim email ke admin akun, dan menulis entri audit.

Percobaan ulang dan dead letter

Respons selain 2xx atau kegagalan jaringan menjadwalkan percobaan ulang:

Percobaan	Jeda setelah percobaan sebelumnya
1	segera
2	15 detik
3	1 menit
4	5 menit
5	30 menit
6	2 jam
7	8 jam
8	24 jam

408, 429, 5xx, dan kesalahan jaringan dicoba ulang. 400, 401, 403, 404, dan 410 tidak: pengiriman langsung masuk ke antrean dead letter, karena mencoba ulang tanda tangan yang ditolak atau endpoint yang tidak ada tidak akan membantu. Setelah delapan percobaan gagal, pengiriman juga dimasukkan ke dead letter.

Dead letter disimpan selama 30 hari dan terlihat di Pengaturan → Plugin → {plugin} → Log webhook → DLQ, tempat admin dapat memutar ulangnya (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Batas

Body keluar: default 1 MB (dapat dikonfigurasi per plugin). Body masuk ke RolChat: 5 MB. Yang lebih besar mendapat 413.
Plugin dapat mendeklarasikan allowed_source_ips; RolChat menerapkan allowlist tersebut sebelum verifikasi.
Anda dapat memeriksa user agent RolChat-Webhook/1.0 sebagai pemeriksaan kewajaran tambahan. Ini bukan kontrol keamanan.

Webhook masuk ke RolChat

Penyedia mengirim ke RolChat di /api/v1/webhooks/{category}/{adapter} menggunakan skema tanda tangan mereka sendiri (Twilio, Telnyx, Bandwidth, Meta untuk WhatsApp, Stripe). Setiap adaptor memverifikasi tanda tangan penyedianya, menormalkan payload, dan menerbitkannya ulang di event bus internal dengan tanda tangan RolChat. Sistem Anda sendiri dapat mengirim ke RolChat dengan header X-RolChat-* yang sama seperti dijelaskan di atas, ditandatangani dengan secret milik plugin pemilik endpoint.

Webhook otomasi

Aksi Kirim permintaan HTTP pada modul Otomasi memiliki aturan pengiriman tersendiri:

Satu secret per akun. Tampilkan atau rotasi di layar Otomasi (Owner dan Admin). Rotasi berlaku seketika: tidak ada jendela tumpang tindih, secret lama langsung berhenti terverifikasi, jadi perbarui penerima Anda terlebih dahulu atau terima jeda singkat.
Waktu tunggu: RolChat menunggu respons selama 10 detik.
Percobaan ulang: hingga 6 percobaan secara total. Jeda sebelum percobaan ke-2 adalah 30 detik, lalu sekitar 2 menit, 8 menit, 32 menit, dan 2 jam 8 menit, masing-masing bervariasi hingga 20 %. Satu jeda tidak pernah melebihi 6 jam.
Yang dicoba ulang: galat jaringan, waktu habis, 5xx, 408, 425, dan 429. Respons 4xx lainnya, alamat yang diblokir, atau body yang terlalu besar tidak dicoba ulang: pengiriman langsung masuk ke antrean dead-letter, seperti setelah percobaan terakhir yang gagal.
Header: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Menguji penerima Anda

POST /api/v1/webhooks/test-signature mengirim event bertanda tangan sintetis ke endpoint plugin pemanggil sehingga Anda dapat memverifikasi implementasi dari ujung ke ujung sebelum trafik nyata datang.

Kesalahan umum

Memverifikasi terhadap JSON yang sudah di-parse dan dienkode ulang, bukan byte mentah.
Menggunakan == untuk membandingkan tanda tangan.
Deduplikasi berdasarkan nonce (setiap percobaan ulang punya nonce baru), bukan berdasarkan ID event.
Jam yang meleset lebih dari lima menit.
Mengerjakan proses lambat sebelum menjawab, lalu kehabisan waktu pada 15 detik dan menerima event yang sama lagi.