Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
Portal webhook Dodo Payments telah dibangun ulang dengan pengalaman dasbor native. Endpoint, signing secret, signature verification, nama event, dan payload webhook yang sudah ada tidak berubah. Tidak diperlukan pekerjaan integrasi.
Lokasi berbagai hal.
Di Developer → Webhooks — tab Endpoints, Event catalog, Logs, Activity, dan Settings.
Pada endpoint individual — tab Overview, yang memuat statistik pengiriman, signing secret, dan Replay history, serta tab Testing dan Advanced dan tindakan replay massal.
Pada pesan — dibuka dari tab Logs, tempat setiap upaya pengiriman dapat di-replay secara terpisah tanpa membuka endpoint.
1
Access Webhook Settings
Buka Dodo Payments Dashboard dan buka Developer → Webhooks.
2
Create Webhook Endpoint
Klik Add endpoint untuk membuka side sheet pembuatan endpoint.
3
Enter Endpoint URL or Choose Integration
Masukkan URL tempat Anda ingin menerima event webhook, atau pilih integration connector untuk merutekan event ke layanan pihak ketiga (Slack, Discord, Zapier, Resend, dan sebagainya).
4
Select Events to Receive
Pilih event tertentu yang harus didengarkan oleh endpoint Anda. Event diatur dalam hierarki yang dapat dicari dan dikelompokkan berdasarkan resource. Anda dapat memilih event individual atau resource induk untuk menerima semua event terkait.
Hanya event yang dipilih yang akan memicu webhook ke endpoint Anda, sehingga membantu menghindari traffic dan pemrosesan yang tidak diperlukan.
5
Create Endpoint
Klik Create endpoint untuk menyimpan konfigurasi Anda.
6
Get Secret Key
Webhook signing secret Anda ditampilkan pada tab Overview endpoint. Anda akan menggunakannya untuk memverifikasi keaslian webhook yang diterima.
Jaga keamanan secret key webhook Anda dan jangan pernah mengeksposnya dalam kode sisi klien atau repositori publik.
7
Rotate Secret (Optional)
Jika diperlukan, Anda dapat merotasi secret webhook untuk meningkatkan keamanan. Klik Rotate secret di samping secret pada tab Overview.
Rotasi secret akan membuatnya kedaluwarsa dan menggantinya dengan secret baru. Secret lama hanya akan valid selama 24 jam berikutnya. Setelah itu, verifikasi menggunakan secret lama akan gagal.
Gunakan rotasi secret secara berkala atau segera jika Anda menduga secret saat ini telah disusupi.
Daripada membangun penerima webhook sendiri, Anda dapat merutekan event webhook secara langsung ke layanan pihak ketiga menggunakan integration connector. Dengan demikian, Anda tidak perlu menulis dan memelihara webhook handler khusus untuk platform populer.
Connector membawa transformasi yang mengonversi event Dodo Payments ke bentuk yang diharapkan oleh tujuan. Detail yang perlu Anda berikan bergantung pada tujuan tersebut:
Jenis connector
Yang Anda berikan
Tujuan
Incoming webhook URL
URL webhook yang Anda buat di dasbor milik vendor. Tidak memerlukan API key.
Pemilih connector di dasbor menampilkan seluruh pilihan yang saat ini tersedia untuk bisnis Anda. Karena itu, anggap tabel di atas sebagai daftar tujuan dengan instruksi penyiapan langkah demi langkah, bukan daftar lengkap. Lihat External Integrations untuk mengetahui kemampuan setiap tujuan setelah event sampai di sana.
Pilih connector saat membuat atau mengedit endpoint, lalu side sheet akan menampilkan instruksi penyiapan yang ditulis untuk tujuan tersebut — misalnya cara membuat incoming webhook URL di Slack atau tempat menemukan Resend API key. Sebelum menyimpan, jalankan pengujian transformasi connector untuk memastikan event dikonversi dengan benar untuk tujuan tersebut.
Gunakan connector untuk menjangkau tujuan yang didukung tanpa menulis kode. Jika Anda memerlukan logika khusus, gunakan endpoint standar dengan transformation.
Anda dapat mengonfigurasi event tertentu yang harus diterima oleh setiap endpoint webhook.
1
Navigate to Webhook Endpoints
Buka Dodo Payments Dashboard dan navigasikan ke Developer → Webhooks.
2
Select Your Endpoint
Klik endpoint webhook yang ingin Anda konfigurasi.
3
Open Event Configuration
Klik Edit untuk membuka side sheet konfigurasi endpoint.
4
Browse Event Types
Pemilih jenis event menampilkan semua event webhook yang tersedia dalam hierarki yang dapat dicari dan dikelompokkan berdasarkan resource (misalnya, payment, subscription, dispute). Gunakan bilah pencarian untuk menemukan event tertentu berdasarkan nama atau kata kunci dengan cepat.
5
Select Events
Centang kotak di samping event yang ingin Anda terima. Anda dapat:
Memilih event individual (misalnya, payment.succeeded, payment.failed)
Memilih resource induk untuk menerima semua event terkait
Mengombinasikan event tertentu sesuai kebutuhan Anda
6
Save Configuration
Klik Save untuk menerapkan perubahan, atau Cancel untuk membatalkan modifikasi.
Jika Anda membatalkan pilihan semua event, endpoint webhook Anda tidak akan menerima notifikasi apa pun. Pastikan Anda memilih setidaknya event yang diperlukan aplikasi agar dapat berfungsi dengan baik.
Buka Developer → Webhooks dan buka tab Event catalog. Tab ini mencantumkan setiap jenis event yang dapat dikirim Dodo Payments, sehingga Anda dapat melihat pilihan yang tersedia sebelum membuat endpoint berlangganan event tersebut. Pilih event untuk melihat skemanya dan contoh payload, cara tercepat untuk memeriksa bentuk field yang ingin Anda baca.
Webhook Events Guide
Telusuri event yang sama sebagai dokumentasi referensi, yang dikelompokkan berdasarkan resource.
Webhook memiliki jendela timeout 15 detik untuk operasi koneksi dan pembacaan. Pastikan endpoint Anda merespons dengan cepat untuk menghindari timeout.
Proses webhook secara asynchronous dengan segera mengonfirmasi penerimaan menggunakan status code 200, lalu lakukan pemrosesan sebenarnya di latar belakang.
Jika pengiriman webhook gagal, Dodo Payments secara otomatis mencoba kembali dengan exponential backoff untuk mencegah sistem Anda kelebihan beban.
Percobaan
Jeda
Deskripsi
1
Segera
Percobaan ulang pertama dilakukan langsung
2
5 detik
Percobaan kedua setelah jeda singkat
3
5 menit
Percobaan ketiga dengan backoff yang ditingkatkan
4
30 menit
Percobaan keempat melanjutkan backoff
5
2 jam
Percobaan kelima dengan jeda yang lebih panjang
6
5 jam
Percobaan keenam dengan jeda yang lebih lama
7
10 jam
Percobaan ketujuh dengan jeda maksimum
8
10 jam
Percobaan terakhir - webhook ditandai gagal jika tidak berhasil
Maksimal 8 percobaan ulang per event webhook. Misalnya, jika webhook gagal tiga kali sebelum berhasil, total waktu pengiriman sekitar 35 menit 5 detik sejak percobaan pertama.
Gunakan dasbor Dodo Payments untuk mencoba kembali pesan individual secara manual atau memulihkan semua pesan yang gagal secara massal kapan saja.
Event webhook dapat tiba tidak berurutan karena percobaan ulang atau kondisi jaringan. Rancang sistem Anda agar dapat menangani event dalam urutan apa pun.
Anda akan menerima payload terbaru pada saat pengiriman, terlepas dari kapan event webhook tersebut awalnya dibuat.
Setiap request webhook menyertakan header webhook-signature, yaitu signature HMAC SHA256 dari payload dan timestamp webhook yang ditandatangani menggunakan secret key Anda.
Jika Anda tidak menggunakan SDK, Anda dapat memverifikasi signature sendiri mengikuti spesifikasi Standard Webhooks:
Buat pesan yang ditandatangani dengan menggabungkan webhook-id, webhook-timestamp, dan string mentah payload yang telah di-stringify secara tepat, dipisahkan oleh titik (.).
Hitung HMAC SHA256 dari string tersebut menggunakan secret key webhook Anda dari Dashboard.
Bandingkan signature yang dihitung dengan header webhook-signature. Jika cocok, webhook tersebut autentik.
Verifikasi signature adalah cara yang didukung untuk mengautentikasi webhook. Cara ini membuktikan bahwa request ditandatangani dengan webhook secret Anda, yang tidak dapat dilakukan oleh pemeriksaan tingkat jaringan.Pengiriman webhook dikirim dari kumpulan alamat IP sumber yang dimiliki oleh infrastruktur pengiriman kami. Kumpulan tersebut dapat berubah dari waktu ke waktu, jadi perlakukan alamat ini sebagai detail operasional, bukan properti integrasi yang tetap.
Jangan gunakan source IP allowlist sebagai mekanisme autentikasi Anda. Allowlist hanya menunjukkan dari mana request berasal, bukan bahwa request tersebut asli atau belum diubah — verifikasi header webhook-signature pada setiap request, seperti yang dijelaskan dalam Memverifikasi Signature.
Jika infrastruktur Anda berada di balik firewall yang memerlukan allowlist eksplisit, perhatikan hal-hal berikut:
Jangan hardcode alamat secara permanen. Rentang alamat ditambahkan dan dihentikan penggunaannya dari waktu ke waktu, dan aturan yang sudah usang akan memblokir pengiriman secara diam-diam.
Minta rentang terbaru dari support@dodopayments.com sebelum Anda membatasi firewall, agar Anda menggunakan daftar yang terbaru.
Pantau pemberitahuan perubahan. Saat alamat pengiriman berubah, kami memberi tahu merchant yang terdampak melalui email — terapkan pembaruan tersebut sebelum tanggal yang disebutkan untuk menghindari pengiriman yang terlewat.
Tetap aktifkan verifikasi signature terlepas dari aturan jaringan apa pun yang Anda tambahkan.
Pada platform serverless dan managed hosting, pemfilteran IP inbound sering kali tidak tersedia atau tidak praktis untuk dipelihara. Verifikasi signature adalah kontrol yang tepat di lingkungan tersebut, dan allowlist tidak diperlukan.
Pengiriman yang diblokir diperlakukan sama seperti kegagalan lainnya dan akan dicoba kembali sesuai jadwal yang dijelaskan dalam Automatic Retries. Jika aturan firewall menyebabkan pengiriman gagal, Anda dapat mengirimnya kembali setelah aturan diperbaiki — lihat Memutar Ulang dan Memulihkan Message.
Jenis resource. Salah satu dari: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt, EntitlementGrant, atau Payout.
Field tambahan bervariasi berdasarkan jenis event. Lihat dokumentasi khusus event untuk schema lengkap.
Anda dapat menguji integrasi webhook langsung dari dashboard Dodo Payments untuk memastikan endpoint Anda berfungsi dengan benar sebelum digunakan di production.
1
Navigate to Webhooks
Buka Dashboard Dodo Payments Anda dan navigasikan ke Developer → Webhooks.
2
Select Your Endpoint
Klik endpoint webhook Anda untuk membuka halaman detailnya.
3
Open Testing Tab
Klik tab Testing untuk mengakses antarmuka pengujian webhook.
Tab Testing mengirimkan sample payload ke endpoint ini agar Anda dapat memverifikasi receiver Anda.
1
Select Event Type
Gunakan Select an event type untuk memilih event yang ingin Anda uji, misalnya payment.succeeded atau payment.failed.
2
Send Example
Klik Send example. Sample payload dikirimkan ke URL endpoint Anda sama seperti event nyata, dengan signature yang sama.
Message yang gagal dikirim dari tab Testing tidak akan dicoba kembali. Gunakan fitur ini untuk memverifikasi receiver Anda, bukan untuk menguji jadwal retry.
3
Check Your Endpoint
Tab ini mencatat kapan Last example sent dikirim. Pastikan event telah tiba, verifikasi signature berhasil, dan Anda mengembalikan status code 2xx.
Uji handler webhook Anda secara menyeluruh menggunakan antarmuka pengujian dashboard sebelum memproses event production. Hal ini membantu mengidentifikasi dan memperbaiki masalah sejak awal.
Teruskan event webhook nyata dari akun test mode Anda ke server pengembangan lokal secara real time:
dodo wh listen
CLI membuka koneksi WebSocket ke Dodo Payments dan meneruskan setiap event webhook ke endpoint lokal Anda (misalnya, http://localhost:3000/webhook), dengan mempertahankan semua header termasuk signature headers untuk pengujian verifikasi.
Listener hanya berfungsi dengan API keys test mode. Jalankan dodo login dan pilih Test Mode sebelum menggunakan command ini.
Kirim mock webhook payload ke endpoint mana pun tanpa membuat transaksi nyata:
dodo wh trigger
Tool interaktif ini memungkinkan Anda memilih jenis event dan mengirimkan mock payload yang realistis ke endpoint Anda. Tool ini berjalan dalam loop sehingga Anda dapat menguji beberapa event dalam satu sesi.Trigger command mencakup semua 47 jenis event yang dikirimkan Dodo Payments, termasuk kelompok subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, dan entitlement grant — lihat Supported Webhook Events untuk daftar lengkapnya.
Mock webhook payload dari dodo wh trigger tidak memiliki signature. Gunakan unsafe_unwrap(), bukan unwrap(), di handler webhook Anda hanya selama pengujian.
Kontrol tingkat pengiriman event webhook ke endpoint Anda untuk mencegah sistem kewalahan.
1
Open Advanced Tab
Dari halaman detail endpoint, klik tab Advanced.
2
Configure Rate Limit
Di bagian “Rate Limit (throttling)”, klik Edit untuk mengubah pengaturan rate limit.
Secara default, webhook tidak memiliki rate limit, yang berarti event dikirim segera setelah terjadi.
3
Set Your Limit
Konfigurasikan rate limit yang diinginkan untuk mengontrol frekuensi pengiriman webhook dan mencegah sistem kelebihan beban.
Gunakan rate limiting saat handler webhook Anda memerlukan waktu untuk memproses event atau saat Anda ingin mengelompokkan beberapa event secara bersamaan.
Tambahkan HTTP headers khusus ke semua request webhook yang dikirim ke endpoint Anda. Ini berguna untuk autentikasi, routing, atau penambahan metadata.
1
Add Headers
Di bagian “Custom Headers”, masukkan Key dan Value untuk setiap custom header.
2
Add Multiple Headers
Klik tombol + untuk menambahkan custom header tambahan sesuai kebutuhan.
Custom headers Anda disertakan dalam semua request webhook ke endpoint ini.
Transformations memungkinkan Anda memodifikasi payload webhook dan, secara opsional, mengarahkannya ke URL yang berbeda. Fitur canggih ini memungkinkan Anda untuk:
Memodifikasi struktur payload sebelum diproses
Mengarahkan webhook ke endpoint berbeda berdasarkan konten
Menambahkan atau menghapus field dari payload
Mengubah format data
1
Enable Transformations
Aktifkan switch Enabled untuk mengaktifkan fitur transformation.
2
Configure Transformation
Klik Edit transformation untuk menentukan aturan transformation menggunakan JavaScript.
3
Test Transformation
Gunakan antarmuka pengujian transformation untuk memastikan transformation Anda berfungsi dengan benar sebelum digunakan di production.
Transformations dapat memengaruhi performa pengiriman webhook. Uji secara menyeluruh dan buat logika transformation tetap sederhana serta efisien.
Tab Logs menyediakan visibilitas menyeluruh terhadap status pengiriman webhook, sehingga Anda dapat memantau, men-debug, dan mengelola event webhook secara efektif.
1
Navigate to Logs Tab
Buka Developer → Webhooks dan buka tab Logs.
2
Browse Delivery History
Lihat tabel semua upaya pengiriman webhook dengan kolom Event type, Message ID, Event ID, Sent at, Attempted at, Response code, dan Duration.
3
Search and Filter
Gunakan search bar untuk menemukan message tertentu berdasarkan ID atau jenis event. Filter berdasarkan status (Succeeded, Failed, Pending, dan lainnya) untuk berfokus pada event yang perlu Anda selidiki.
4
View Message Details
Klik message apa pun untuk membuka halaman detail message, yang menampilkan:
Payload webhook lengkap
Setiap upaya pengiriman beserta response code dan durasinya
Timestamp setiap upaya
Pesan error apa pun dari endpoint Anda
Setiap upaya memiliki tindakan Replay, sehingga Anda dapat mengirim ulang message tersebut tanpa meninggalkan halaman.
Buka Developer → Webhooks dan buka tab Activity untuk melihat performa pengiriman di seluruh endpoint Anda.Delivery activity menampilkan upaya dari waktu ke waktu, yang dikelompokkan sebagai Attempts per 5 minutes, Attempts per hour, atau Attempts per day sesuai rentang waktu. Setiap batang dibagi berdasarkan hasil, dan saat Anda mengarahkan kursor ke suatu segmen, status, jumlah upaya, serta bagiannya dari total akan ditampilkan. Pada endpoint, Delivery stats (last 24h) di tab Overview merangkum informasi yang sama untuk satu hari terakhir.
Kolom Error rate (24h) pada tab Endpoints memberi tahu Anda secara sekilas endpoint mana yang memerlukan perhatian, sebelum Anda membukanya.
Buka endpoint dari Developer → Webhooks. Tersedia tiga mode, dan masing-masing hanya berlaku untuk endpoint tersebut. Rentang yang Anda tetapkan bergantung pada mode:
Mode
Fungsinya
Yang Anda tetapkan
Recover failed messages
Memutar ulang setiap message ke endpoint ini yang gagal.
Titik awal: 8 hours ago, Yesterday, 3 days ago, Last week, atau 2 weeks ago
Replay missing messages
Memutar ulang message yang tidak pernah dikirim ke endpoint ini, misalnya setelah Anda subscribe endpoint ke jenis event baru.
Titik awal yang sama
Bulk replay messages
Memutar ulang message yang sesuai dengan filter yang Anda pilih, termasuk message yang sebelumnya telah berhasil dikirim.
Batas Since dan Until, dengan default dua minggu terakhir, ditambah jenis event, channel, atau tag opsional
1
Open More Actions
Pada endpoint, buka More actions dan pilih salah satu dari tiga mode di atas.
2
Set the Range
Isi rentang yang diminta oleh mode tersebut, seperti yang tercantum dalam tabel.
3
Start the Run
Klik Recover atau Replay, sesuai mode yang Anda pilih.
Setiap proses akan muncul di bagian Replay history pada tab Overview endpoint, beserta modenya, rentang waktu, status, dan jumlah message yang dikirim ulang.
Siap men-deploy handler webhook Anda ke production? Kami menyediakan panduan khusus platform untuk membantu Anda men-deploy webhook ke cloud provider populer dengan praktik terbaik untuk setiap platform.
Vercel
Deploy webhook ke Vercel dengan serverless functions
Cloudflare Workers
Jalankan webhook di edge network Cloudflare
Supabase Edge Functions
Integrasikan webhook dengan Supabase
Netlify Functions
Deploy webhook sebagai serverless functions Netlify
Setiap panduan platform mencakup penyiapan environment, verifikasi signature, dan langkah deployment khusus untuk provider tersebut.