Apa Itu Webhook? Cara Aplikasi Saling Memberi Kabar

Webhook adalah pesan otomatis yang dikirim sebuah layanan ke aplikasi Anda tepat saat sesuatu terjadi. Ketika pembayaran pelanggan berhasil, Stripe mengirim webhook ke sebuah alamat di aplikasi Anda yang berisi “pembayaran berhasil, ini detailnya”, dan aplikasi Anda bereaksi — menandai pesanan sebagai lunas, mengirim kwitansi, membuka akses akun. Singkatnya: API adalah aplikasi Anda bertanya sesuatu ke layanan lain; webhook adalah layanan lain yang memanggil aplikasi Anda untuk memberi tahu sesuatu.

Mengapa ini penting saat membangun dengan AI

Begitu aplikasi Anda menerima pembayaran, menerima data formulir dari alat lain, atau terhubung ke layanan seperti GitHub, Shopify, atau kalender, Anda akan bertemu webhook. Webhook biasanya cara yang benar untuk mengetahui sesuatu telah terjadi — tetapi di sinilah aplikasi yang dibangun dengan AI sering kali keliru secara halus:

• Endpoint menerima permintaan apa pun, sehingga siapa pun bisa memalsukan peristiwa “pembayaran berhasil”.
• Aplikasi memberikan akses di halaman redirect checkout, bukan di webhook, sehingga orang yang menutup tab lebih awal tidak mendapatkan apa yang sudah mereka bayar, dan orang yang menemukan URL halaman sukses mendapatkannya gratis.
• Peristiwa yang sama tiba dua kali dan pelanggan mendapat dua pesanan atau dua email.

Memahami cara kerja webhook membuat Anda bisa meminta perlindungan ini sejak awal.

Analogi sehari-hari: pesan dari kurir

Anda bisa mengetahui apakah paket Anda sudah tiba dengan dua cara. Anda bisa terus berjalan ke pintu depan setiap sepuluh menit untuk memeriksa (itu disebut polling — aplikasi Anda berulang kali memanggil API untuk bertanya “ada yang baru?”). Atau kurir bisa mengirim SMS ketika paket sudah diantar (itulah webhook).

SMS jelas lebih baik — selama Anda bisa mempercayainya. Jika siapa pun bisa mengirim pesan “paket sudah diantar”, Anda perlu cara untuk memastikan pesan itu benar-benar berasal dari kurir. Dan jika ponsel Anda mati saat SMS datang, Anda ingin kurir mencoba lagi nanti. Dua hal itu — verifikasi dan percobaan ulang — adalah sebagian besar yang membuat webhook rumit.

Cara kerja webhook, langkah demi langkah

1. Anda membuat endpoint di backend aplikasi: sebuah URL seperti https://aplikasianda.com/webhooks/stripe yang menerima permintaan POST.
2. Anda mendaftarkan URL itu ke penyedia dan memilih peristiwa yang ingin Anda terima (misalnya, “checkout selesai” dan “langganan dibatalkan”).
3. Penyedia memberi Anda signing secret. Anda menyimpannya sebagai secret di server Anda — lihat environment variables dan secrets.
4. Sebuah peristiwa terjadi. Penyedia mengirim permintaan HTTP ke URL Anda dengan body JSON yang menjelaskan peristiwa tersebut, ditambah header tanda tangan.
5. Aplikasi Anda memverifikasi tanda tangan, mencatat ID peristiwa, membalas dengan kode sukses (200) secepatnya, lalu mengerjakan tugasnya.
6. Jika aplikasi Anda tidak membalas dengan sukses, banyak penyedia akan mencoba lagi nanti.

Tanda tangan

Tanda tangan membuktikan bahwa permintaan berasal dari penyedia dan tidak diubah. Stripe, misalnya, menghitung HMAC (semacam sidik jari berkunci) dengan SHA-256 atas body permintaan dan timestamp, menggunakan signing secret, lalu mengirimkannya di header Stripe-Signature. Aplikasi Anda melakukan perhitungan yang sama dengan salinan secret miliknya; jika hasilnya cocok, permintaan itu asli. Karena timestamp juga ditandatangani, Anda bisa menolak permintaan lama yang direkam seseorang dan diputar ulang nanti — library Stripe menggunakan toleransi lima menit secara default, menurut dokumentasi Stripe per September 2026.

Satu detail praktis: tanda tangan dihitung dari body permintaan mentah. Jika framework Anda mengurai dan memformat ulang JSON sebelum Anda memverifikasi, pemeriksaan akan gagal. Ini bug yang sangat umum.

Percobaan ulang, duplikat, dan urutan

Penyedia berbeda satu sama lain, jadi periksa dokumentasi masing-masing. Per September 2026:

Dokumentasi Stripe juga menyebutkan bahwa peristiwa tidak dijamin tiba sesuai urutan kejadiannya, dan peristiwa yang sama kadang bisa tiba lebih dari sekali, sehingga Stripe menyarankan untuk mencatat ID peristiwa.

Pelajaran umumnya berlaku untuk penyedia mana pun: peristiwa bisa tiba terlambat, lebih dari sekali, dan tidak berurutan. Handler Anda sebaiknya bersifat idempoten — memproses peristiwa yang sama dua kali menghasilkan efek yang sama seperti memprosesnya sekali.

Contoh nyata: membuka kursus berbayar

Anda menjual kursus online. Seorang siswa mengklik Beli, membayar di halaman checkout yang dihosting Stripe, lalu dikembalikan ke situs Anda.

Cara yang rapuh: halaman “terima kasih” membuka kursus. Jika siswa menutup browser saat proses redirect, mereka sudah membayar tetapi tidak punya akses. Jika seseorang menebak URL halaman terima kasih, mereka mendapat akses tanpa membayar.

Cara webhook:

1. Ketika Stripe mengonfirmasi pembayaran, ia mengirim peristiwa checkout.session.completed ke /webhooks/stripe.
2. Backend Anda memverifikasi tanda tangan dengan signing secret. Jika gagal, ia membalas 400 dan tidak melakukan apa pun.
3. Ia memeriksa apakah ID peristiwa itu sudah pernah diproses. Jika ya, ia membalas 200 dan berhenti.
4. Ia menyimpan ID peristiwa, membalas 200, lalu memberikan akses kepada siswa dan mengirim email selamat datang.
5. Halaman terima kasih hanya menampilkan “Pembayaran diterima — kursus Anda akan muncul sebentar lagi” dan memeriksa status akses siswa.

Nanti, jika langganan dibatalkan atau kartu gagal ditagih, peristiwa webhook lain memberi tahu aplikasi Anda untuk mencabut atau menjeda akses. Begitulah produk berlangganan tetap sinkron dengan penagihan — lihat apa itu SaaS dan cara menambahkan pembayaran ke aplikasi Anda.

Istilah kunci

• Endpoint: URL di aplikasi Anda yang menerima webhook.
• Event / payload: apa yang terjadi, dan data yang menjelaskannya (biasanya JSON).
• Signing secret: secret bersama yang digunakan untuk memverifikasi tanda tangan.
• Idempoten: aman dijalankan lebih dari sekali dengan hasil yang sama.
• Polling: berulang kali bertanya ke sebuah API tentang perubahan, alih-alih menunggu webhook.
• Tunnel: alat yang memberi laptop URL publik sementara agar webhook bisa mencapainya selama pengembangan.

Kesalahan umum dan kesalahpahaman

• Tidak memverifikasi tanda tangan. URL endpoint bukan rahasia. Verifikasilah yang membuat permintaan tepercaya.
• Mengerjakan tugas berat sebelum membalas. Mengirim email atau membuat PDF sebelum merespons bisa menyebabkan timeout, yang memicu percobaan ulang, yang menyebabkan duplikat.
• Menganggap pasti sekali, berurutan. Catat ID peristiwa dan jangan bergantung pada urutan kedatangan.
• Menggunakan URL preview. Webhook membutuhkan alamat publik yang stabil. Preview privat dan localhost tidak bisa dijangkau dari internet; gunakan URL publikasi Anda (atau tunnel saat menguji).
• Mencampur secret uji dan live. Penyedia sering mengeluarkan signing secret yang berbeda untuk mode uji dan live. Simpan keduanya dan gunakan yang tepat.
• Memercayai payload begitu saja untuk keputusan penting. Untuk tindakan berisiko tinggi, wajar jika Anda mengambil status terbaru dari API penyedia setelah menerima peristiwa.

Yang harus diminta dari AI builder Anda

Tambahkan endpoint POST /webhooks/stripe di server. Verifikasi tanda tangan Stripe menggunakan body permintaan mentah dan secret STRIPE_WEBHOOK_SECRET. Tolak tanda tangan yang tidak valid dengan 400. Simpan setiap ID peristiwa dan lewati peristiwa yang sudah diproses. Balas 200 secepatnya, lalu tangani checkout.session.completed dengan menandai pesanan lunas dan mengirim kwitansi. Catat jenis peristiwanya. Jangan memberikan akses dari halaman sukses checkout.

Lalu uji: kirim peristiwa uji dari dasbor penyedia, kirim peristiwa yang sama lagi, dan kirim permintaan dengan tanda tangan yang salah. Hanya yang pertama seharusnya mengubah sesuatu.

Webhook di Mythex

Mythex tidak menjalankan layanan webhook terpisah; Anda meminta agen menambahkan endpoint webhook di backend aplikasi Anda sendiri, lalu mengarahkan penyedia ke URL publikasi Anda, karena webhook membutuhkan alamat publik. Signing secret disimpan di secrets proyek Anda, dan jika Anda mengubahnya pada aplikasi live, Anda perlu mempublikasikan ulang. Resep dokumentasi tentang menangani webhook memiliki starter prompt, dan template toko adalah titik awal yang baik untuk aplikasi yang menerima pembayaran.

Pertanyaan