Alur singkat
- Kamu membuat endpoint
POSTdi server, misalnya/webhooks/simplus. - Simplus mengirim pesan JSON ke endpoint itu, lengkap dengan header
svix-id,svix-timestamp, dansvix-signature. - Endpoint kamu membaca raw body, memverifikasi signature dengan Signing Secret, lalu membalas
2xxsecepatnya. - Pekerjaan berat (simpan ke database, sinkronisasi ke ERP, dan sebagainya) dijalankan di background lewat queue.
Membuat endpoint penerima
Siapkan dulu Signing Secret endpoint kamu dari portal webhook (lihat Mengaktifkan Webhook), lalu simpan di environment variable:.env
- Membaca raw body persis seperti yang dikirim.
- Memverifikasi signature. Kalau gagal, membalas
400. - Menangani event
sales.persisted. - Membalas
204secepatnya, lalu memproses data di background.
Mencoba di lokal
Portal webhook hanya bisa mengirim ke URL publik, jadilocalhost perlu dibuka ke internet dulu. Pilih salah satu cara berikut.
- Svix CLI
- ngrok
- Svix Play (tanpa kode)
Svix CLI bisa membuat URL publik sementara yang meneruskan semua request ke server lokal kamu. Tidak perlu akun Svix.CLI akan menampilkan URL publik dengan format
https://play.svix.com/in/<id>/, plus link untuk melihat log request. Pakai URL https://play.svix.com/in/... itu sebagai Endpoint URL di portal.1
Daftarkan URL di portal
Buka portal webhook, klik Add Endpoint, isi Endpoint URL dengan URL publik tadi, centang
sales.persisted, lalu klik Create. Detailnya ada di Mengaktifkan Webhook.2
Pakai Signing Secret endpoint ini
Setiap endpoint punya Signing Secret sendiri. Salin Signing Secret endpoint baru ini ke
SIMPLUS_WEBHOOK_SECRET di lokal, lalu restart server.3
Kirim contoh event
Di halaman endpoint, buka tab Testing, pilih
sales.persisted, lalu klik Send Example. Server lokal kamu akan menerima contoh payload, dan statusnya muncul di Message Attempts.Checklist sebelum production
- HTTPS saja. Endpoint production harus memakai
https. - Selalu verifikasi signature. Jangan percaya isi payload sebelum signature valid.
- Balas
2xxdalam beberapa detik. Svix memberi waktu sekitar 15 detik. Lebih dari itu dianggap gagal, jadi pindahkan pekerjaan berat ke queue. - Idempotent dengan
svix-id. Pesan yang sama bisa diterima lebih dari sekali karena retry. Simpansvix-idyang sudah diproses, dan lewati kalau datang lagi. - Simpan versi terbaru. Satu transaksi bisa memicu beberapa event
sales.persisted, dan urutan sampainya tidak dijamin. Setiap event berisi data transaksi lengkap, jadi simpan berdasarkandata.id. Kalau urutan penting, ambil ulang transaksi lewat API Simplus sebelum menyimpan. - Siap untuk retry. Pesan yang gagal dicoba ulang otomatis dengan jeda yang makin lama. Jadwal lengkapnya ada di dokumentasi retry Svix.
- Simpan secret dengan aman. Taruh Signing Secret di environment variable atau secret manager. Kalau bocor, rotasi secret dari halaman endpoint di portal webhook, lalu update server kamu.
- Ambil ulang data kalau perlu. Untuk data yang sangat penting, ambil ulang transaksi dari API Simplus memakai API Key sebelum diproses.
Troubleshooting
Verifikasi selalu gagal (Invalid signature)
Verifikasi selalu gagal (Invalid signature)
- Body sudah di-parse. Pastikan kamu memakai raw body:
express.raw()di Express,$request->getContent()di Laravel,await request.body()di FastAPI,request.get_data()di Flask. - Secret salah. Setiap endpoint punya Signing Secret sendiri. Pastikan secret yang dipakai berasal dari endpoint yang menerima pesan, termasuk prefix
whsec_. - Endpoint tertukar. Kalau kamu punya beberapa endpoint (misalnya lokal dan production), cek URL di portal dan secret di server sesuai pasangannya.
- Jam server tidak sinkron. Pesan dengan timestamp lebih dari sekitar 5 menit dari jam server akan ditolak. Aktifkan sinkronisasi waktu (NTP) di server kamu.
Endpoint dinonaktifkan otomatis
Endpoint dinonaktifkan otomatis
Kalau semua pengiriman ke endpoint gagal terus dalam waktu lama, endpoint bisa dinonaktifkan. Perbaiki penyebabnya dulu (cek response di Message Attempts), aktifkan kembali endpoint di portal, lalu kirim ulang pesan yang gagal dengan Replay.
Tidak ada pesan yang masuk
Tidak ada pesan yang masuk
- Webhook belum aktif. Pastikan toggle Webhook sudah aktif di aplikasi Simplus (lihat Mengaktifkan Webhook).
- Filter event. Cek Subscribed events di halaman endpoint. Pastikan
sales.persistedtercentang. - URL tidak bisa diakses. Pastikan URL publik, memakai
https, dan tidak diblokir firewall. Coba kirim dari tab Testing lalu cek Message Attempts. - Route salah. Pastikan path dan method (
POST) di server sama persis dengan URL di portal.
Bagaimana Simplus bisa membantu
Dengan webhook Simplus, setiap transaksi dari kasir langsung sampai ke sistem kamu tanpa polling. Pengiriman, retry, signature, dan log sudah diurus otomatis, jadi kamu cukup fokus memproses data, misalnya untuk sinkronisasi ke software akuntansi, ERP, atau dashboard internal.Langkah berikutnya
Verifikasi Signature
Pahami cara kerja signature dan verifikasi tanpa library.
Event sales.persisted
Lihat struktur payload transaksi penjualan.
