Event
Rekod perubahan pada pembayaran, game session, semakan KYC, bonus, profil pemain, atau objek lain.
Dokumentasi / Webhook
Webhook dan event delivery
Sediakan penghantaran status dan event yang boleh dipercayai antar-sistem: dari penciptaan mesej dan signature verification hingga acknowledgement, redelivery, dan error control.
Event
status dan perubahan
Signature
pengesahan ketulenan
Retry
redelivery
Kawalan
rekod dan diagnosis
Event flow
Dari penciptaan hingga acknowledgement
01
Buat event
Tentukan identifier, tipe, masa, objek, status, dan data berkaitan.
02
Sign dan hantar
Hantar event melalui HTTPS dengan signature dan timeout terbatas.
03
Pengesahan penerimaan
Selepas disahkan, simpan event kemudian segera kembalikan HTTP response yang berjaya.
04
Ulangi jika berlaku error
Lakukan redelivery dengan selang yang meningkat dan simpan event yang belum telah dihantar untuk dianalisis.
Ringkasan
Webhook memberi tahu perubahan status
Sender boleh mengulangi delivery, sehingga receiver mesti mengesahkan sumber, mengakui penerimaan, dan menggunakan setiap event hanya satu kali.
Acknowledgement
Receiver mengembalikan HTTP response berjaya selepas event disahkan dan disimpan dengan selamat.
Recovery
Redelivery dan rekonsiliasi membantu memulihkan data selepas salah satu sistem tidak tersedia buat sementara waktu.
Struktur event
Data yang mesti ada dalam event
Struktur mesej yang seragam menyederhanakan pengesahan, routing, duplicate protection, dan sokongan untuk pelbagai jenis event.
Event ID
Nilai unik yang digunakan sistem untuk mengenali redelivery dan menemui rekod pemprosesan.
Event type
Nama stabil dan jelas yang menentukan perubahan yang berlaku serta cara pemrosesannya.
Masa penciptaan
Tarikh dan masa event dibuat dalam format dan zon masa yang dipersetujui.
Objek berkaitan
Jenis dan identifier pembayaran, pemain, round, request, bonus, atau objek lain.
Versi struktur
Nombor versi membantu mengubah struktur mesej secara selamat tanpa merusak integrasi aktif.
Korelasi dengan operasi
Identifier request awal, transaksi, session, atau rangkaian tindakan berkaitan.
Konteks
Brand, projek, pasaran, environment, provider, dan data lain yang diperlukan untuk routing yang betul.
Event data
Kumpulan field minimum untuk memproses perubahan atau melakukan request lanjutan ke API.
Signature dan pengesahan
Pengesahan ketulenan dan integritas event
Sebelum mengubah data, receiver menyemak sambungan selamat, signature, timestamp, dan event ID unik.
01
Dapatkan mesej asli
Pengesahan signature terhadap raw request body sebelum format JSON diubah.
02
Semak masa
Tolak request jika masa event berada di luar selang yang dibenarkan.
03
Pengesahan signature
Gunakan secret yang dipersetujui dan algoritma HMAC atau digital signature.
04
Semak identifier
Pastikan event belum pernah digunakan dan simpan hasil verifikasinya.
Delivery dan retry
HTTP response dan redelivery
Sender mesti membedakan penerimaan berjaya, error sementara, dan penolakan permanen; receiver mesti merespons dengan pantas dan jelas.
HTTP response berjaya
Mengesahkan bahawa event telah disahkan dan disimpan dengan selamat untuk diproses lebih lanjut.
Timeout terbatas
Jangan melakukan pemprosesan lama sebelum membalas sender — simpan event terlebih dahulu.
Redelivery
Ulangi delivery jika ada network error sementara, perkhidmatan tidak tersedia, atau tiada response.
Penambahbaikan selang
Tingkatkan jeda antarpercobaan secara berperingkat supaya tidak menambah beban sistem.
Dead-letter queue
Selepas keseluruhan percubaan habis, simpan event untuk diagnosis dan pemprosesan manual.
Penghantaran semula manual
Operator boleh menghantar semula event terpilih tanpa membuat operasi baharu.
Delivery monitoring
Pantau jumlah percubaan, response, error terakhir, dan masa penghantaran seterusnya.
Notifikasi
Beri tahu pasukan jika error meningkat, percubaan habis, atau event menumpuk di queue.
Pemprosesan event
Duplicate protection dan turutan status
Receiver tidak boleh mengandalkan delivery satu kali atau turutan event yang selalu ketat.
Pelaksanaan satu kali
Simpan event ID sebelum mengubah data.
Akui duplicate event tanpa mengulangi debit, credit, atau perubahan.
Hubungkan event dengan objek dan statusnya semasa ini.
Simpan event dan perubahan perniagaan sebagai satu operasi yang konsisten.
Turutan dan aktualitas
Bandingkan timestamp, sequence number, atau event version.
Jangan mengembalikan objek ke status lama kesan delayed delivery.
Hanya izinkan peralihan status yang sah.
Jika ragu, minta status objek terkini melalui API.
Testing
Apa yang perlu diuji sebelum pelancaran
Uji delivery berjaya, signature salah, duplicate event, response perlahan, event out-of-order, dan recovery selepas gangguan.
Signature tidak sah
Mesej diubah, key tidak dikenal, timestamp tamat tempoh, atau algoritma tidak disokong.
Redelivery
Event yang sama datang beberapa kali sebelum dan selepas pemprosesan selesai.
Response perlahan
Receiver merespons terlalu lama, sambungan terputus, atau acknowledgement tidak sampai ke sender.
Turutan tidak sesuai
Status final datang sebelum status antara, dan event lama diterima selepas event baharu.
Endpoint tidak tersedia
Uji HTTP 5xx, DNS, TLS, rate had, dan keadaan ketika semua percubaan habis.
Delivery history
Semua percubaan, response, error, dan hasil penghantaran manual mesti boleh ditemui berdasarkan event ID.
Senarai semak sebelum pelancaran
Production delivery diaktifkan selepas keselamatan, duplicate protection, redelivery, dan error control disahkan.
Test dan production environment menggunakan endpoint dan signing secret yang berbeza.
Signature disahkan terhadap raw message dengan mempertimbangkan timestamp.
Event ID disimpan dan melindungi operasi dari pelaksanaan berulang.
Receiver segera mengembalikan HTTP response berjaya selepas event disimpan.
Retry, backoff, dan manual replay telah disediakan.
Delivery history dan carian berdasarkan identifier tersedia untuk support team.
Perlu menyediakan event delivery yang boleh dipercayai?
Hantar senarai event, receiving endpoint, dan peraturan perubahan status. APIACE akan membantu menentukan struktur mesej, signature verification, redelivery, dan error control.