Webhook: Saat Server yang Menghubungimu

Berlangganan koran vs mengecek loper tiap jam

Dua cara tahu berita terbaru: menelepon loper koran tiap jam (polling), atau berlangganan sehingga koran diantar saat terbit (webhook). Webhook adalah URL di server-mu yang dipanggil layanan lain SAAT ada kejadian: pembayaran sukses, pesan baru, deploy selesai. Kamu tidak bertanya berulang-ulang; kamu diberi tahu.

Kenapa webhook mengalahkan polling

Polling (setInterval + fetch tiap 5 detik) boros: 99% request menjawab "belum ada yang baru". Webhook membalik arah: satu request keluar hanya saat ada kejadian nyata. Untuk notifikasi pembayaran, status pengiriman, atau integrasi antar layanan, webhook adalah pola standar industri.

Contoh 1: menerima webhook di Express

app.post("/webhook/pembayaran", function(req, res) {
  const event = req.body;
  if (event.tipe === "pembayaran.sukses") {
    tandaiPesananLunas(event.data.order_id);
  }
  res.status(200).send("OK");
});

Kuncinya: respons CEPAT (200 segera), proses berat lakukan di background. Provider webhook akan retry kalau kamu lama merespons atau mengembalikan error.

Contoh 2: verifikasi signature (wajib!)

Tanpa verifikasi, siapa pun bisa memanggil URL webhook-mu dan berpura-pura jadi provider:

const crypto = require("crypto");

function validasiSignature(body, signature, secret) {
  const hitung = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(body))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(hitung), Buffer.from(signature)
  );
}

Provider mengirim signature di header (misalnya X-Signature). Kamu hitung ulang dengan secret yang hanya kalian berdua tahu. Cocok berarti asli. Jangan pernah skip langkah ini untuk webhook pembayaran.

Kesalahan umum

Salah: tidak verifikasi signature. Webhook palsu bisa menandai pesanan "lunas" tanpa bayar. Yang benar: selalu verifikasi, tolak yang tidak valid dengan 401.

Salah: memproses lama sebelum respons. Provider menganggap gagal dan retry, pesanan diproses dua kali. Yang benar: respons 200 dulu, proses di queue/background.

Salah: tidak idempotent. Retry provider mengeksekusi aksi dua kali. Yang benar: cek event id sudah diproses atau belum sebelum eksekusi.

Salah: memakai GET untuk webhook. Data event terlihat di log dan URL. Yang benar: webhook selalu POST dengan body dan signature di header.

Studi kasus: notifikasi pembayaran QRIS

Alur nyata payment gateway (misalnya Midtrans/Xendit):

1. User scan QRIS dan bayar. Kamu TIDAK tahu kapan tepatnya pembayaran terjadi.
2. Tanpa webhook: frontend polling GET /api/status-bayar tiap 3 detik. Boros dan lambat.
3. Dengan webhook: gateway memanggil POST /webhook/qris di server-mu begitu pembayaran sukses, lengkap dengan signature.
4. Server-mu verifikasi signature, tandai pesanan lunas, lalu dorong notifikasi ke frontend via WebSocket/SSE.

Polling butuh ratusan request untuk satu pembayaran; webhook butuh satu. Untuk integrasi pembayaran, webhook bukan pilihan, melainkan keharusan.

Catatan teknis: Untuk mencoba webhook lokal, pakai tools seperti ngrok atau webhook.site: dapat URL publik sementara, lihat payload mentahnya, lalu arahkan ke localhost-mu. Cara tercepat memahami format webhook provider apa pun.