Event
Catatan perubahan pada pembayaran, game session, pemeriksaan KYC, bonus, profil pemain, atau objek lainnya.
Dokumentasi / Webhook
Webhook dan event delivery
Siapkan pengiriman status dan event yang andal antar-sistem: dari pembuatan pesan dan signature verification hingga acknowledgement, redelivery, dan error control.
Event
status dan perubahan
Signature
verifikasi keaslian
Retry
redelivery
Kontrol
riwayat dan diagnosis
Event flow
Dari pembuatan hingga acknowledgement
01
Buat event
Tentukan identifier, tipe, waktu, objek, status, dan data terkait.
02
Sign dan kirim
Kirim event melalui HTTPS dengan signature dan timeout terbatas.
03
Konfirmasi penerimaan
Setelah diverifikasi, simpan event lalu segera kembalikan HTTP response yang berhasil.
04
Ulangi jika terjadi error
Lakukan redelivery dengan interval yang meningkat dan simpan event yang belum terkirim untuk dianalisis.
Ringkasan
Webhook memberi tahu perubahan status
Sender dapat mengulang delivery, sehingga receiver harus memverifikasi sumber, mengakui penerimaan, dan menerapkan setiap event hanya satu kali.
Acknowledgement
Receiver mengembalikan HTTP response berhasil setelah event diverifikasi dan disimpan dengan aman.
Recovery
Redelivery dan rekonsiliasi membantu memulihkan data setelah salah satu sistem sementara tidak tersedia.
Struktur event
Data yang harus ada dalam event
Struktur pesan yang seragam menyederhanakan verifikasi, routing, duplicate protection, dan dukungan untuk berbagai jenis event.
Event ID
Nilai unik yang digunakan sistem untuk mengenali redelivery dan menemukan riwayat pemrosesan.
Event type
Nama stabil dan jelas yang menentukan perubahan yang terjadi serta cara pemrosesannya.
Waktu pembuatan
Tanggal dan waktu event dibuat dalam format dan zona waktu yang disepakati.
Objek terkait
Jenis dan identifier pembayaran, pemain, round, request, bonus, atau objek lainnya.
Versi struktur
Nomor versi membantu mengubah struktur pesan secara aman tanpa merusak integrasi aktif.
Korelasi dengan operasi
Identifier request awal, transaksi, session, atau rangkaian tindakan terkait.
Konteks
Brand, proyek, pasar, environment, provider, dan data lain yang dibutuhkan untuk routing yang benar.
Event data
Kumpulan field minimum untuk memproses perubahan atau melakukan request lanjutan ke API.
Signature dan verifikasi
Verifikasi keaslian dan integritas event
Sebelum mengubah data, receiver memeriksa koneksi aman, signature, timestamp, dan event ID unik.
01
Dapatkan pesan asli
Verifikasi signature terhadap raw request body sebelum format JSON diubah.
02
Periksa waktu
Tolak request jika waktu event berada di luar interval yang diizinkan.
03
Verifikasi signature
Gunakan secret yang disepakati dan algoritma HMAC atau digital signature.
04
Periksa identifier
Pastikan event belum pernah diterapkan dan simpan hasil verifikasinya.
Delivery dan retry
HTTP response dan redelivery
Sender harus membedakan penerimaan berhasil, error sementara, dan penolakan permanen; receiver harus merespons dengan cepat dan jelas.
HTTP response berhasil
Mengonfirmasi bahwa event telah diverifikasi dan disimpan dengan aman untuk diproses lebih lanjut.
Timeout terbatas
Jangan melakukan pemrosesan lama sebelum membalas sender — simpan event terlebih dahulu.
Redelivery
Ulangi delivery jika ada network error sementara, layanan tidak tersedia, atau tidak ada response.
Peningkatan interval
Tingkatkan jeda antarpercobaan secara bertahap agar tidak menambah beban sistem.
Dead-letter queue
Setelah seluruh percobaan habis, simpan event untuk diagnosis dan pemrosesan manual.
Pengiriman ulang manual
Operator dapat mengirim ulang event terpilih tanpa membuat operasi baru.
Delivery monitoring
Pantau jumlah percobaan, response, error terakhir, dan waktu pengiriman berikutnya.
Notifikasi
Beri tahu tim jika error meningkat, percobaan habis, atau event menumpuk di queue.
Pemrosesan event
Duplicate protection dan urutan status
Receiver tidak boleh mengandalkan delivery satu kali atau urutan event yang selalu ketat.
Penerapan satu kali
Simpan event ID sebelum mengubah data.
Akui duplicate event tanpa mengulang debit, credit, atau perubahan.
Hubungkan event dengan objek dan statusnya saat ini.
Simpan event dan perubahan bisnis sebagai satu operasi yang konsisten.
Urutan dan aktualitas
Bandingkan timestamp, sequence number, atau event version.
Jangan mengembalikan objek ke status lama akibat delayed delivery.
Hanya izinkan transisi status yang valid.
Jika ragu, minta status objek terbaru melalui API.
Testing
Apa yang perlu diuji sebelum peluncuran
Uji delivery berhasil, signature salah, duplicate event, response lambat, event out-of-order, dan recovery setelah gangguan.
Signature tidak valid
Pesan diubah, key tidak dikenal, timestamp kedaluwarsa, atau algoritma tidak didukung.
Redelivery
Event yang sama datang beberapa kali sebelum dan setelah pemrosesan selesai.
Response lambat
Receiver merespons terlalu lama, koneksi terputus, atau acknowledgement tidak sampai ke sender.
Urutan tidak sesuai
Status final datang sebelum status antara, dan event lama diterima setelah event baru.
Endpoint tidak tersedia
Uji HTTP 5xx, DNS, TLS, rate limit, dan kondisi ketika semua percobaan habis.
Delivery history
Semua percobaan, response, error, dan hasil pengiriman manual harus dapat ditemukan berdasarkan event ID.
Checklist sebelum peluncuran
Production delivery diaktifkan setelah keamanan, duplicate protection, redelivery, dan error control diverifikasi.
Test dan production environment menggunakan endpoint dan signing secret yang berbeda.
Signature diverifikasi terhadap raw message dengan mempertimbangkan timestamp.
Event ID disimpan dan melindungi operasi dari eksekusi berulang.
Receiver segera mengembalikan HTTP response berhasil setelah event disimpan.
Retry, backoff, dan manual replay telah disiapkan.
Delivery history dan pencarian berdasarkan identifier tersedia untuk support team.
Perlu menyiapkan event delivery yang andal?
Kirim daftar event, receiving endpoint, dan aturan perubahan status. APIACE akan membantu menentukan struktur pesan, signature verification, redelivery, dan error control.