
Key Features
Webhook menyediakan pengiriman real-time dengan keamanan bawaan, retry otomatis, dan filtering event. Semua SDK resmi menyertakan helper verifikasi signature, dan dashboard menyediakan alat untuk pengujian, pemantauan, serta replay.Getting Started
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
Integration Connectors
Teruskan event webhook langsung ke layanan pihak ketiga menggunakan integration connector, sehingga Anda tidak perlu membuat dan memelihara handler webhook khusus.Cara Kerja Connector
Connector mengubah event Dodo Payments ke format yang diharapkan oleh tujuan. Detail yang perlu Anda berikan bergantung pada tujuan tersebut:Menyiapkan Connector
Saat membuat atau mengedit endpoint, pilih connector dan side sheet akan menampilkan petunjuk penyiapan untuk tujuan tersebut. Uji transformasi sebelum menyimpan untuk memastikan event dikonversi dengan benar.Mengonfigurasi Event yang Di-subscribe
Konfigurasikan event yang diterima setiap endpoint webhook.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Centang kotak di samping event yang ingin diterima. Anda dapat memilih event individual, seluruh resource, atau kombinasi keduanya.Save Configuration
Katalog Event
Buka Developer → Webhooks lalu buka tab Event catalog untuk melihat setiap jenis event yang dapat dikirim Dodo Payments. Pilih event untuk melihat schema dan contoh payload-nya.Webhook Events Guide
Pengiriman Webhook
Timeout
Webhook memiliki timeout 30 detik untuk operasi koneksi dan pembacaan. Proses webhook secara asinkron dengan segera mengembalikan status code200, lalu tangani event di latar belakang.
Percobaan Ulang Otomatis
Pengiriman yang gagal akan dicoba ulang dengan exponential backoff, hingga total 8 percobaan:Idempotensi
Setiap webhook menyertakan headerwebhook-id yang unik. Simpan ID ini untuk mendeteksi dan melewati event duplikat, karena percobaan ulang dapat mengirimkan event yang sama beberapa kali.
Urutan Event
Event dapat tiba tidak berurutan karena percobaan ulang atau kondisi jaringan. Setiap webhook menyertakan fieldtimestamp; gunakan field ini untuk mengurutkan event jika aplikasi Anda memerlukannya. Anda selalu menerima status payload terbaru pada waktu pengiriman.
Mengamankan Webhook
Selalu validasi payload webhook dan gunakan HTTPS.Memverifikasi Signature
Setiap webhook menyertakan headerwebhook-signature: signature HMAC SHA256 dari payload dan timestamp, yang ditandatangani dengan secret key Anda.
Verifikasi SDK (Direkomendasikan)
Semua SDK resmi menyertakan helper bawaan. TetapkanDODO_PAYMENTS_WEBHOOK_KEY saat menginisialisasi client, lalu panggil unwrap() untuk memverifikasi dan mengurai payload. Tersedia dua metode:
unwrap— Memverifikasi signature dengan secret key webhook Anda, lalu mengurai payload.unsafe_unwrap— Mengurai payload tanpa memverifikasinya. Gunakan hanya untuk pengujian.
unwrap / unsafeUnwrap dalam TypeScript, unwrap / unsafe_unwrap dalam Python, dan Unwrap / UnsafeUnwrap dalam Go.
Verifikasi Manual (Alternatif)
Jika Anda tidak menggunakan SDK, verifikasi signature sendiri:- Buat konten bertanda tangan dengan menggabungkan
webhook-id,webhook-timestamp, dan request body mentah dengan titik:{id}.{timestamp}.{body}. Gunakan body mentah persis seperti yang diterima, sebelum penguraian JSON apa pun. - Ambil secret webhook Anda. Jika diawali
whsec_, hapus prefix tersebut, lalu lakukan base64-decode pada sisanya untuk mendapatkan signing key. - Hitung HMAC-SHA256 dari konten bertanda tangan menggunakan signing key, lalu lakukan base64-encode pada hasilnya.
- Header
webhook-signatureberisi satu atau beberapa signature yang dipisahkan spasi, masing-masing dalam bentukv1,<base64-signature>. Request valid jika signaturev1mana pun cocok dengan milik Anda. Bandingkan menggunakan fungsi constant-time. - Tolak request jika
webhook-timestampterlalu jauh dari waktu saat ini untuk mencegah replay attack. Library Standard Webhooks mengizinkan 5 menit.
Alamat IP Sumber
Verifikasi signature adalah metode autentikasi yang didukung. Metode ini membuktikan bahwa request ditandatangani dengan secret webhook Anda, sesuatu yang tidak dapat dilakukan oleh pemeriksaan tingkat jaringan. Pengiriman webhook berasal dari kumpulan alamat IP yang berubah seiring waktu. Jangan mengandalkan allowlist IP untuk autentikasi. Selalu verifikasi headerwebhook-signature, seperti dijelaskan dalam Memverifikasi Signature.
Jika firewall Anda memerlukan allowlist:
- Jangan hardcode alamat secara permanen. Rentang berubah seiring waktu, dan aturan yang usang dapat diam-diam memblokir pengiriman.
- Minta rentang terbaru dari support@dodopayments.com sebelum memperketat firewall.
- Pantau pemberitahuan perubahan. Saat alamat pengiriman berubah, kami memberi tahu merchant yang terdampak melalui email — terapkan pembaruan sebelum tanggal yang ditentukan.
- Tetap aktifkan verifikasi signature terlepas dari aturan jaringan apa pun yang Anda tambahkan.
Merespons Webhook
Handler webhook Anda harus mengembalikan2xx status code untuk mengonfirmasi penerimaan. Respons lainnya dianggap gagal dan webhook akan dicoba ulang.
Praktik Terbaik
- Gunakan HTTPS saja. Endpoint HTTP rentan terhadap penyadapan.
- Respons dengan segera. Segera kembalikan status code
200, lalu proses event secara asinkron. - Terapkan idempotensi. Gunakan header
webhook-iduntuk mendeteksi dan melewati event duplikat. - Amankan secret Anda. Simpan
DODO_PAYMENTS_WEBHOOK_KEYdalam environment variables atau secrets manager, jangan pernah di version control.
Struktur Payload Webhook
Format Request
Header
Request Body
payment.succeeded, subscription.active).Contoh Payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed dan pulihkan pembayaran yang ditolakMenguji Webhook
Mengirim Contoh Event
Uji integrasi webhook langsung dari dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Contoh Implementasi
Implementasi Express.js lengkap dengan verifikasi dan penanganan webhook:Menguji Webhook dengan CLI
Dodo Payments CLI memiliki dua perintah untuk menguji webhook selama pengembangan lokal.Mendengarkan Webhook Langsung Secara Lokal
Teruskan event webhook nyata dari akun test mode Anda ke server pengembangan lokal:http://localhost:3000/webhook), dengan mempertahankan semua header untuk pengujian verifikasi signature.
dodo login dan pilih Test Mode terlebih dahulu.Memicu Event Mock Webhook
Kirim payload webhook mock ke endpoint mana pun tanpa membuat transaksi nyata:subscription.past_due atau subscription.unpaused. Lihat Supported Webhook Events untuk daftar lengkapnya.
CLI Webhook Testing Docs
Pengaturan Lanjutan
Tab Advanced menyediakan opsi konfigurasi tambahan untuk menyempurnakan perilaku endpoint webhook Anda.Pembatasan Rate (Throttling)
Kontrol laju pengiriman event webhook ke endpoint Anda. Secara default, webhook tidak memiliki rate limit dan event dikirim segera setelah terjadi.Open Advanced Tab
Configure Rate Limit
Set Your Limit
Header Kustom
Tambahkan header HTTP kustom ke semua request webhook yang dikirim ke endpoint Anda. Berguna untuk autentikasi, routing, atau penambahan metadata.Add Headers
Add Multiple Headers
Transformasi
Transformasi memungkinkan Anda mengubah payload webhook dan secara opsional mengarahkannya ke URL lain. Gunakan transformasi untuk:- Mengubah struktur payload sebelum diproses
- Merutekan webhook ke endpoint berbeda berdasarkan konten
- Menambahkan atau menghapus field dari payload
- Mengubah format data
Enable Transformations
Configure Transformation
handler().Test Transformation
Memantau Log Webhook
Tab Logs memberikan visibilitas terhadap status pengiriman webhook Anda.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- Payload webhook lengkap
- Setiap percobaan pengiriman dengan response code dan durasi
- Timestamp setiap percobaan
- Pesan error apa pun dari endpoint Anda
Pemantauan Aktivitas
Buka Developer → Webhooks dan buka tab Activity untuk melihat performa pengiriman di seluruh endpoint Anda. Delivery activity memplot percobaan dari waktu ke waktu, dikelompokkan sebagai Attempts per 5 minutes, Attempts per hour, atau Attempts per day bergantung pada rentang waktu. Setiap batang dibagi berdasarkan hasil, dan saat mengarahkan kursor ke segmen, status, jumlah percobaan, serta porsinya dari total akan ditampilkan. Pada endpoint, Delivery stats (last 24h) di tab Overview merangkum informasi yang sama untuk hari sebelumnya.Memutar Ulang dan Memulihkan Pesan
Cara Anda mengirim ulang pesan bergantung pada jumlah pesan yang diperlukan:- Satu pesan — buka dari tab Logs dan gunakan tindakan Replay pada percobaan tersebut.
- Rentang pesan — buka endpoint, karena mode massal hanya berlaku untuk satu endpoint dalam satu waktu.
Memutar Ulang Secara Massal
Buka endpoint dari Developer → Webhooks. Tersedia tiga mode, dan masing-masing hanya berlaku untuk endpoint tersebut:Open More Actions
Set the Range
Start the Run