Bayangkan seorang pelanggan membeli produk melalui toko online. Ia memilih metode pembayaran, menyelesaikan transaksi, lalu menutup halaman pembayaran. Beberapa saat kemudian, pembayaran berhasil.

Namun, bagaimana website toko mengetahui bahwa uang sudah dibayarkan jika pelanggan tidak kembali ke halaman toko?

Jika aplikasi hanya mengandalkan informasi yang dikirim melalui browser pelanggan, perubahan status transaksi bisa terlewat. Pelanggan mungkin menutup browser, kehilangan koneksi internet, atau tidak kembali setelah pembayaran selesai.

Masalah seperti ini membutuhkan mekanisme komunikasi yang tidak bergantung pada aktivitas pelanggan di browser. Salah satu solusi yang banyak digunakan dalam sistem pembayaran digital adalah webhook.

Melalui webhook, penyedia layanan pembayaran dapat mengirimkan pemberitahuan langsung ke server merchant ketika terjadi peristiwa tertentu, seperti perubahan status invoice atau pembayaran berhasil.

Dengan mekanisme ini, aplikasi bisnis dapat memperbarui status pesanan, mengirim konfirmasi kepada pelanggan, atau menjalankan proses berikutnya tanpa harus menunggu pelanggan kembali ke website.

Apa Itu Webhook?

Webhook adalah mekanisme komunikasi antarsistem yang memungkinkan sebuah aplikasi mengirimkan data secara otomatis ke aplikasi lain ketika suatu peristiwa terjadi.

Dalam konteks pembayaran, webhook biasanya digunakan oleh penyedia layanan pembayaran untuk memberitahukan perubahan status transaksi kepada sistem merchant.

Misalnya, sebuah toko online membuat invoice melalui payment gateway. Ketika pelanggan menyelesaikan pembayaran dan penyedia mencatat transaksi sebagai berhasil, sistem pembayaran mengirimkan HTTP request ke alamat server yang telah didaftarkan oleh merchant.

Server merchant menerima pemberitahuan tersebut, memeriksa keabsahan pesan, kemudian memperbarui status transaksi di database.

Berbeda dengan komunikasi API yang umumnya dilakukan ketika aplikasi secara aktif meminta data, webhook bekerja berdasarkan peristiwa. Sistem penerima tidak perlu terus-menerus bertanya apakah pembayaran sudah berhasil.

Karena itu, webhook sering disebut sebagai mekanisme event-driven communication atau komunikasi berbasis peristiwa.

Mengapa Sistem Pembayaran Membutuhkan Webhook?

Dalam transaksi digital, proses pembayaran dan proses memperbarui pesanan tidak selalu berlangsung pada waktu yang sama.

Pelanggan bisa menyelesaikan pembayaran melalui aplikasi mobile banking atau dompet digital, sementara website merchant berjalan di server yang berbeda. Kedua sistem tersebut tidak selalu berkomunikasi secara langsung melalui browser pelanggan.

Tanpa webhook, merchant perlu menyediakan mekanisme tambahan untuk mengetahui perubahan status pembayaran.

Salah satu pendekatannya adalah melakukan polling, yaitu meminta status transaksi secara berkala melalui API. Pendekatan ini dapat bekerja, tetapi memiliki konsekuensi operasional.

Jika aplikasi memeriksa status setiap beberapa detik, jumlah request akan meningkat meskipun belum ada perubahan transaksi. Jika interval terlalu lama, pembaruan status juga dapat terlambat diketahui.

Webhook memberikan pendekatan yang berbeda. Penyedia pembayaran mengirimkan pemberitahuan ketika peristiwa yang relevan terjadi.

Beberapa manfaatnya antara lain:

1. Memperbarui status pesanan secara otomatis

Ketika pembayaran telah dikonfirmasi, aplikasi merchant dapat mengubah status pesanan tanpa menunggu pelanggan kembali ke website.

2. Mengurangi pemeriksaan status berulang

Merchant tidak harus terus-menerus mengirim request untuk mengetahui apakah invoice sudah berubah status.

3. Menjalankan proses bisnis berikutnya

Sistem dapat mengirim email konfirmasi, mengaktifkan akses layanan digital, membuat tiket pesanan, atau memulai proses pengiriman setelah status pembayaran memenuhi ketentuan.

4. Mendukung transaksi asinkron

Pembayaran tidak selalu selesai tepat ketika pelanggan menekan tombol bayar. Beberapa metode pembayaran memerlukan waktu pemrosesan tambahan. Webhook membantu aplikasi menerima perubahan status ketika hasilnya sudah tersedia.

Bagaimana Cara Kerja Webhook dalam Transaksi Pembayaran?

Untuk memahami mekanismenya, bayangkan sebuah toko online yang menggunakan layanan payment gateway untuk menerima pembayaran.

Alur sederhananya berlangsung sebagai berikut.

1. Merchant membuat transaksi

Ketika pelanggan melakukan checkout, backend merchant mengirimkan permintaan pembuatan invoice melalui API penyedia pembayaran.

Permintaan tersebut biasanya berisi informasi seperti nominal, deskripsi pesanan, identitas referensi transaksi, dan waktu kedaluwarsa.

Penyedia pembayaran kemudian mengembalikan informasi invoice beserta halaman pembayaran atau instruksi pembayaran yang dapat digunakan pelanggan.

2. Pelanggan menyelesaikan pembayaran

Pelanggan membuka halaman pembayaran dan memilih metode yang tersedia.

Setelah menyelesaikan instruksi pembayaran, sistem pembayaran memproses transaksi sesuai mekanisme metode yang digunakan.

Pada tahap ini, website merchant belum tentu langsung mengetahui hasil akhirnya.

3. Penyedia pembayaran mencatat perubahan status

Setelah hasil transaksi tersedia dan tercatat dalam sistem penyedia pembayaran, status invoice dapat berubah.

Contohnya, invoice yang sebelumnya pending berubah menjadi paid.

Perubahan inilah yang dapat memicu pembuatan event webhook.

4. Webhook dikirim ke server merchant

Penyedia pembayaran mengirimkan HTTP request, umumnya menggunakan metode POST, ke endpoint webhook yang telah didaftarkan merchant.

Request tersebut berisi informasi mengenai event yang terjadi, termasuk identitas event dan data transaksi yang relevan.

Endpoint webhook merupakan alamat khusus pada backend merchant yang disiapkan untuk menerima pemberitahuan tersebut.

5. Server merchant memverifikasi dan memproses event

Server merchant tidak boleh langsung mempercayai setiap request yang masuk.

Sistem perlu memeriksa signature, memastikan event berasal dari penyedia yang benar, dan mengecek apakah event tersebut sudah pernah diproses.

Jika valid, aplikasi dapat memperbarui status transaksi dan menjalankan tindakan bisnis yang sesuai.

6. Server memberikan respons

Setelah event diterima dan disimpan dengan aman, server merchant mengembalikan respons HTTP 2xx.

Respons ini memberi tahu pengirim bahwa endpoint berhasil menerima pemberitahuan.

Jika server tidak dapat memproses atau menerima request dengan benar, penyedia pembayaran dapat mencatat kegagalan dan mencoba mengirimkannya kembali sesuai kebijakan retry.

Dengan demikian, webhook memungkinkan komunikasi pembayaran berlangsung secara otomatis antara dua server tanpa bergantung pada browser pelanggan.

Contoh Data Webhook Pembayaran

Webhook biasanya membawa payload dalam format JSON. Struktur dan nama field dapat berbeda antara satu penyedia dengan penyedia lainnya.

Berikut contoh ilustrasi sederhana:

{
  "id": "evt_123456789",
  "type": "invoice.status_changed",
  "created_at": "2026-11-13T02:00:00Z",
  "data": {
    "invoice_id": "inv_123456",
    "order_id": "ORD-2026-001",
    "status": "paid",
    "amount": 150000,
    "currency": "IDR",
    "paid_at": "2026-11-13T02:00:00Z"
  }
}

Dari contoh tersebut, beberapa informasi memiliki fungsi penting.

  • id merupakan identitas unik event yang dapat digunakan untuk mencegah pemrosesan berulang.

  • type menjelaskan jenis peristiwa yang dikirimkan.

  • invoice_id mengidentifikasi invoice pada sistem pembayaran.

  • order_id menghubungkan transaksi dengan pesanan pada aplikasi merchant.

  • status menunjukkan status invoice yang tercatat.

  • amount menunjukkan nominal transaksi.

  • paid_at menunjukkan waktu pembayaran dicatat berhasil.

Payload tersebut hanya ilustrasi, bukan kontrak API dari penyedia tertentu. Developer harus selalu mengikuti struktur resmi yang disediakan oleh layanan pembayaran yang digunakan.

Webhook Tidak Boleh Langsung Dipercaya

Webhook merupakan komunikasi antarsistem yang melewati jaringan publik. Artinya, endpoint penerima harus memiliki mekanisme untuk memastikan bahwa request benar-benar berasal dari penyedia pembayaran yang dipercaya.

Jika aplikasi hanya memeriksa isi JSON dan menemukan status paid, sistem berisiko menerima pemberitahuan palsu dari pihak yang tidak berwenang.

Karena itu, implementasi webhook membutuhkan beberapa lapisan pengamanan.

Verifikasi Signature

Penyedia pembayaran umumnya menyediakan mekanisme signature berbasis secret yang hanya diketahui oleh pengirim dan penerima.

Salah satu metode yang digunakan adalah HMAC-SHA256.

Pengirim membuat tanda tangan digital berdasarkan secret dan data tertentu, kemudian menyertakannya dalam header HTTP. Server merchant menghitung ulang signature menggunakan secret yang dimiliki dan membandingkan hasilnya dengan signature yang diterima.

Jika hasilnya cocok, request memiliki integritas sesuai mekanisme verifikasi yang digunakan.

Penting untuk memverifikasi signature menggunakan raw request body, yaitu isi request asli sebelum JSON diubah atau diproses ulang. Perubahan format, spasi, atau serialisasi dapat menghasilkan signature yang berbeda.

Validasi Timestamp

Beberapa sistem menyertakan timestamp dalam signature.

Server merchant dapat memeriksa apakah waktu pengiriman masih berada dalam rentang yang diterima. Mekanisme ini membantu mengurangi risiko replay attack, yaitu penggunaan kembali request valid yang pernah dikirim sebelumnya.

Deduplikasi Event

Setiap event sebaiknya memiliki identitas unik.

Server merchant perlu menyimpan ID tersebut dan memeriksa apakah event sudah pernah diproses. Jika event yang sama diterima kembali, aplikasi tidak boleh menjalankan tindakan bisnis untuk kedua kalinya.

Mengamankan Endpoint

Endpoint webhook sebaiknya menggunakan HTTPS. Secret harus disimpan di server, bukan pada frontend atau repositori publik.

Selain itu, informasi sensitif seperti API key, webhook secret, dan data autentikasi tidak boleh dicatat sembarangan dalam log aplikasi.

Mengapa Webhook Bisa Dikirim Lebih dari Satu Kali?

Salah satu karakteristik penting webhook adalah pengiriman ulang atau retry.

Misalnya, penyedia pembayaran sudah mengirimkan event bahwa invoice berhasil dibayar. Namun, server merchant sedang mengalami gangguan sehingga tidak memberikan respons HTTP 2xx.

Dari sisi penyedia, pengiriman tersebut belum dapat dianggap berhasil. Sistem dapat mencoba mengirimkan event yang sama kembali setelah beberapa waktu.

Pengiriman ulang juga dapat terjadi ketika terjadi timeout atau gangguan jaringan, meskipun server merchant sebenarnya sudah menerima dan memproses request sebelumnya.

Kondisi ini membuat sistem merchant harus siap menerima event yang sama lebih dari satu kali.

Ada tiga hal yang perlu diperhatikan.

Pertama, jangan menganggap setiap request sebagai transaksi baru.

Event ID harus digunakan untuk mengenali apakah pemberitahuan tersebut sudah pernah diterima dan diproses.

Kedua, buat pemrosesan bersifat idempoten.

Jika event yang sama diproses berulang, hasil akhirnya harus tetap sama. Misalnya, pesanan yang sudah berstatus lunas tidak boleh kembali menjalankan proses pemberian akses atau pengiriman produk hanya karena webhook dikirim ulang.

Ketiga, simpan event sebelum memberikan respons sukses.

Untuk sistem yang memiliki volume transaksi cukup tinggi, pendekatan yang lebih aman adalah menyimpan event secara durable ke database atau antrean pekerjaan terlebih dahulu. Setelah event berhasil diterima dan disimpan, endpoint dapat mengembalikan respons 2xx, sementara pemrosesan bisnis dilanjutkan oleh worker.

Dengan pendekatan tersebut, gangguan pada proses lanjutan tidak serta-merta membuat event yang sudah diterima hilang.

Apa yang Harus Dilakukan Jika Webhook Gagal?

Kegagalan webhook dapat disebabkan oleh berbagai hal, seperti server merchant tidak aktif, timeout, konfigurasi URL salah, signature tidak cocok, atau kesalahan pada kode penerima.

Penanganannya perlu dibedakan berdasarkan sumber masalah.

Jika endpoint tidak dapat diakses, periksa konfigurasi DNS, HTTPS, firewall, dan kondisi server.

Jika terjadi timeout, periksa apakah endpoint menjalankan terlalu banyak proses sebelum memberikan respons. Proses berat dapat dipindahkan ke background worker setelah event disimpan.

Jika signature tidak cocok, pastikan secret yang digunakan sesuai dengan lingkungan transaksi, raw body tidak berubah, dan format signature mengikuti dokumentasi penyedia.

Jika event diterima berulang, periksa mekanisme deduplikasi dan pastikan pemrosesan bisnis idempoten.

Jika pengiriman terus gagal, periksa delivery log pada dashboard penyedia pembayaran. Informasi tersebut biasanya membantu mengetahui kode HTTP, waktu percobaan, dan penyebab kegagalan.

Selain retry otomatis, beberapa penyedia menyediakan fitur pengiriman ulang secara manual. Fitur ini berguna ketika endpoint merchant sudah diperbaiki dan event sebelumnya masih perlu diproses.

Merchant juga sebaiknya menyediakan mekanisme rekonsiliasi melalui API untuk memeriksa kembali status invoice jika pemberitahuan tidak diterima atau ada ketidaksesuaian data.

Webhook merupakan mekanisme notifikasi, bukan satu-satunya cara untuk memeriksa kebenaran status transaksi.

Webhook dan API: Apa Perbedaannya?

Webhook dan API sering digunakan bersama dalam integrasi pembayaran, tetapi keduanya memiliki pola komunikasi yang berbeda.

Aspek

API Request

Webhook

Pemicu komunikasi

Aplikasi meminta data atau menjalankan operasi

Peristiwa tertentu terjadi

Arah komunikasi

Client mengirim request ke server API

Penyedia mengirim request ke endpoint merchant

Waktu komunikasi

Ketika aplikasi membutuhkan respons

Ketika event yang relevan terjadi

Contoh

Merchant meminta detail invoice

Penyedia memberitahukan invoice berubah menjadi paid

Kebutuhan utama

Mengambil atau mengubah data

Menerima pemberitahuan otomatis

Keduanya bukan teknologi yang saling menggantikan.

API digunakan ketika aplikasi perlu membuat invoice, mengambil status, atau menjalankan operasi lain. Webhook digunakan ketika aplikasi perlu mengetahui bahwa suatu peristiwa telah terjadi.

Dalam sistem pembayaran yang terintegrasi dengan baik, API dan webhook justru saling melengkapi.

Contoh Penerapan Webhook pada Bisnis Digital

Webhook tidak hanya bermanfaat untuk toko online. Berbagai jenis bisnis digital dapat menggunakannya untuk menghubungkan pembayaran dengan proses operasional.

Toko online

Ketika pembayaran berhasil, sistem dapat memperbarui status pesanan, mengirim konfirmasi, dan memulai proses pengemasan.

Platform SaaS

Setelah pembayaran langganan berhasil dikonfirmasi, sistem dapat mengaktifkan atau memperpanjang masa akses pelanggan.

Marketplace

Webhook dapat membantu memperbarui status pembayaran pesanan dan memulai proses operasional berikutnya sesuai aturan marketplace.

Sistem pemesanan jasa

Aplikasi dapat mengonfirmasi jadwal atau mengubah status pemesanan setelah pembayaran tercatat berhasil.

Sistem invoice bisnis

Perubahan status pembayaran dapat digunakan untuk memperbarui catatan piutang dan menandai tagihan yang telah diselesaikan.

Dalam semua contoh tersebut, tindakan bisnis tetap harus mengikuti status transaksi yang sah dan aturan masing-masing aplikasi.

Menggunakan Webhook dalam Integrasi PembayaranKU

PembayaranKU menyediakan REST API V1 dan webhook untuk membantu merchant mengintegrasikan proses pembayaran dengan website atau aplikasi mereka.

Setelah merchant membuat invoice melalui API, perubahan status invoice yang relevan dapat dikirimkan ke endpoint webhook yang telah dikonfigurasi melalui Dashboard → Developer.

Dokumentasi PembayaranKU menyediakan beberapa event, antara lain:

  • invoice.status_changed untuk perubahan status invoice.

  • payment.confirmation_changed untuk perubahan status konfirmasi payment record.

  • webhook.test untuk menguji konfigurasi pengiriman webhook.

Setiap event dilengkapi identitas event, waktu kejadian, dan data yang diperlukan untuk mengenali perubahan tersebut.

PembayaranKU menggunakan HMAC-SHA256 untuk verifikasi signature. Header pengiriman mencakup event ID, jenis event, timestamp, dan signature. Merchant perlu memverifikasi signature terhadap raw request body sebelum memproses payload.

Sistem juga menyediakan mekanisme retry dan delivery log untuk membantu merchant menangani kegagalan pengiriman. Jika event yang sama dikirim kembali, merchant perlu menggunakan event ID untuk mencegah pemrosesan ganda.

Ada satu hal penting mengenai status transaksi PembayaranKU yang perlu dipahami developer.

Status matched menunjukkan notifikasi Android Companion berhasil dicocokkan dengan invoice. Status verified merupakan tahapan verifikasi internal PembayaranKU. Keduanya bukan konfirmasi settlement resmi dari bank atau penyedia jasa pembayaran.

Status invoice paid merupakan status final yang digunakan merchant untuk memproses pesanan sebagai sudah dibayar.

Karena itu, aplikasi merchant tidak boleh mengaktifkan pesanan hanya berdasarkan status matched atau verified.

Untuk pengujian integrasi, PembayaranKU juga menyediakan lingkungan Sandbox yang terpisah dari Live. Developer dapat menyimulasikan perubahan status invoice tanpa melakukan pembayaran QRIS sungguhan. Webhook Sandbox memiliki URL dan signing secret tersendiri sehingga tidak tercampur dengan transaksi produksi.

Panduan lengkap mengenai konfigurasi endpoint, struktur event, verifikasi signature, retry, dan integrasi tersedia di Dokumentasi Developer PembayaranKU.

Webhook yang Andal Membutuhkan Lebih dari Sekadar Endpoint

Webhook membuat komunikasi antara penyedia pembayaran dan aplikasi merchant menjadi lebih otomatis. Namun, keberhasilan integrasi tidak cukup hanya dengan menyediakan satu URL untuk menerima HTTP request.

Developer perlu memastikan setiap event diverifikasi, disimpan dengan aman, dideduplikasi, dan diproses sesuai status transaksi yang benar.

Sistem juga perlu memiliki mekanisme pemulihan ketika terjadi gangguan jaringan atau kegagalan server. API untuk pemeriksaan ulang status transaksi dapat menjadi pelengkap ketika pemberitahuan tidak diterima atau hasil pemrosesan perlu dipastikan kembali.

Dengan rancangan yang tepat, webhook membantu bisnis menjaga konsistensi data pembayaran dan status pesanan, sekaligus mengurangi ketergantungan pada proses manual.

Pada akhirnya, tujuan webhook bukan hanya membuat aplikasi mengetahui bahwa pembayaran berhasil, tetapi memastikan setiap perubahan transaksi dapat diterjemahkan menjadi tindakan bisnis yang benar, aman, dan dapat dipertanggungjawabkan.