Skip to main content
Buat endpoint di server kamu untuk menerima, memverifikasi, dan memproses webhook Simplus dari awal sampai siap production.

Alur singkat

  1. Kamu membuat endpoint POST di server, misalnya /webhooks/simplus.
  2. Simplus mengirim pesan JSON ke endpoint itu, lengkap dengan header svix-id, svix-timestamp, dan svix-signature.
  3. Endpoint kamu membaca raw body, memverifikasi signature dengan Signing Secret, lalu membalas 2xx secepatnya.
  4. 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
Contoh di bawah memakai library resmi Svix. Semua contoh melakukan hal yang sama:
  • Membaca raw body persis seperti yang dikirim.
  • Memverifikasi signature. Kalau gagal, membalas 400.
  • Menangani event sales.persisted.
  • Membalas 204 secepatnya, lalu memproses data di background.
Verifikasi selalu dari raw body. Kalau body sudah di-parse lalu di-stringify ulang (misalnya lewat express.json() atau $request->all()), urutan atau spasi bisa berubah dan verifikasi akan gagal.
Mau tahu apa yang terjadi di dalam library? Lihat Verifikasi Signature untuk cara kerjanya dan contoh verifikasi tanpa library.

Mencoba di lokal

Portal webhook hanya bisa mengirim ke URL publik, jadi localhost perlu dibuka ke internet dulu. Pilih salah satu cara berikut.
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.
Setelah punya URL publik:
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.
Hapus endpoint uji coba dari portal setelah selesai, supaya event asli tidak terkirim ke URL sementara.

Checklist sebelum production

  • HTTPS saja. Endpoint production harus memakai https.
  • Selalu verifikasi signature. Jangan percaya isi payload sebelum signature valid.
  • Balas 2xx dalam 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. Simpan svix-id yang 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 berdasarkan data.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

  • 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.
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.
  • Webhook belum aktif. Pastikan toggle Webhook sudah aktif di aplikasi Simplus (lihat Mengaktifkan Webhook).
  • Filter event. Cek Subscribed events di halaman endpoint. Pastikan sales.persisted tercentang.
  • 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.