Skip to main content
Gambar Sampul Webhook
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.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

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.

Integration Connectors

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.

Cara Kerja Connector

Connector membawa transformasi yang mengonversi event Dodo Payments ke bentuk yang diharapkan oleh tujuan. Detail yang perlu Anda berikan bergantung pada tujuan tersebut: 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.

Menyiapkan Connector

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.

Mengonfigurasi Event yang Dilanggani

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.

Katalog Event

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.

Pengiriman Webhook

Timeout

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.

Percobaan Ulang Otomatis

Jika pengiriman webhook gagal, Dodo Payments secara otomatis mencoba kembali dengan exponential backoff untuk mencegah sistem Anda kelebihan beban.
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.

Idempotensi

Setiap event webhook menyertakan header webhook-id yang unik. Gunakan identifier ini untuk menerapkan idempotensi dan mencegah pemrosesan duplikat.
Selalu terapkan pemeriksaan idempotensi. Karena adanya percobaan ulang, Anda mungkin menerima event yang sama beberapa kali.

Urutan Event

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.

Mengamankan Webhook

Untuk memastikan keamanan webhook, selalu validasi payload dan gunakan HTTPS.

Memverifikasi Signature

Setiap request webhook menyertakan header webhook-signature, yaitu signature HMAC SHA256 dari payload dan timestamp webhook yang ditandatangani menggunakan secret key Anda.

Verifikasi SDK (disarankan)

Semua SDK resmi menyertakan helper bawaan untuk memvalidasi dan mem-parsing webhook masuk dengan aman. Tersedia dua metode:
  • unwrap(): Memverifikasi signature menggunakan secret key webhook Anda
  • unsafe_unwrap(): Mem-parsing payload tanpa verifikasi
Berikan secret webhook melalui DODO_PAYMENTS_WEBHOOK_KEY saat menginisialisasi klien Dodo Payments.

Verifikasi Manual (alternatif)

Jika Anda tidak menggunakan SDK, Anda dapat memverifikasi signature sendiri mengikuti spesifikasi Standard Webhooks:
  1. Buat pesan yang ditandatangani dengan menggabungkan webhook-id, webhook-timestamp, dan string mentah payload yang telah di-stringify secara tepat, dipisahkan oleh titik (.).
  2. Hitung HMAC SHA256 dari string tersebut menggunakan secret key webhook Anda dari Dashboard.
  3. Bandingkan signature yang dihitung dengan header webhook-signature. Jika cocok, webhook tersebut autentik.
Kami mengikuti spesifikasi Standard Webhooks. Anda dapat menggunakan library mereka untuk memverifikasi signature: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Untuk format payload event, lihat Webhook Payload.

Merespons Webhook

  • Webhook handler Anda harus mengembalikan 2xx status code untuk mengonfirmasi penerimaan event.
  • Respons lainnya akan dianggap sebagai kegagalan, dan webhook akan dicoba kembali.

Praktik Terbaik

Selalu gunakan URL HTTPS untuk endpoint webhook. Endpoint HTTP rentan terhadap serangan man-in-the-middle dan dapat mengekspos data webhook Anda.
Kembalikan status code 200 segera setelah menerima webhook. Proses event secara asynchronous untuk menghindari timeout.
Terapkan idempotensi menggunakan header webhook-id agar event yang sama dapat diproses beberapa kali dengan aman tanpa efek samping.
Simpan secret webhook Anda dengan aman menggunakan environment variables atau secrets manager. Jangan pernah melakukan commit secret ke version control.

Struktur Payload Webhook

Memahami struktur payload webhook membantu Anda mem-parsing dan memproses event dengan benar.

Format Request

string
wajib
Identifier unik untuk event webhook ini. Gunakan untuk pemeriksaan idempotensi.
string
wajib
Signature HMAC SHA256 untuk memverifikasi keaslian webhook.
string
wajib
Timestamp Unix (dalam detik) saat webhook dikirim.

Body Request

string
wajib
Identifier bisnis Dodo Payments Anda.
string
wajib
Jenis event yang memicu webhook ini (misalnya, payment.succeeded, subscription.active).
string
wajib
Timestamp berformat ISO 8601 saat event terjadi.
object
wajib
Payload khusus event yang berisi informasi terperinci tentang event.

Contoh Payload

Event Types

Telusuri semua jenis event webhook yang tersedia

Event Payloads

Lihat skema payload terperinci untuk setiap event

Handle Payment Failures

Tanggapi payment.failed dan pulihkan pembayaran yang ditolak

Menguji Webhook

Anda dapat menguji integrasi webhook langsung dari dasbor Dodo Payments untuk memastikan endpoint berfungsi dengan benar sebelum digunakan di production.
1

Navigate to Webhooks

Buka Dodo Payments Dashboard 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 membuka antarmuka pengujian webhook.

Mengirim Contoh Event

Tab Testing mengirimkan contoh payload ke endpoint ini agar Anda dapat memverifikasi penerima webhook.
1

Select Event Type

Gunakan Select an event type untuk memilih event yang ingin diuji, misalnya payment.succeeded atau payment.failed.
2

Send Example

Klik Send example. Contoh payload dikirim ke URL endpoint Anda persis seperti event nyata, dengan signature yang sama.
Pesan yang gagal dikirim dari tab Testing tidak akan dicoba kembali. Gunakan fitur ini untuk memverifikasi penerima webhook, bukan untuk menguji jadwal percobaan ulang.
3

Check Your Endpoint

Tab ini mencatat waktu Last example sent dikirim. Pastikan event telah tiba, verifikasi signature berhasil, dan Anda mengembalikan status code 2xx.

Contoh Implementasi

Berikut implementasi Express.js lengkap yang menunjukkan verifikasi dan penanganan webhook:
Uji webhook handler Anda secara menyeluruh menggunakan antarmuka pengujian dasbor sebelum memproses event production. Hal ini membantu menemukan dan memperbaiki masalah sejak awal.

Menguji Webhook dengan CLI

Dodo Payments CLI menyediakan dua perintah untuk menguji webhook selama pengembangan lokal tanpa perlu meninggalkan terminal.

Mendengarkan Webhook Live Secara Lokal

Teruskan event webhook nyata dari akun test mode ke server pengembangan lokal Anda secara real time:
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 header untuk pengujian verifikasi.
Listener hanya berfungsi dengan API key test mode. Jalankan dodo login dan pilih Test Mode sebelum menggunakan perintah ini.

Memicu Event Webhook Mock

Kirim payload webhook mock ke endpoint apa pun tanpa membuat transaksi nyata:
Alat interaktif ini memungkinkan Anda memilih jenis event dan mengirim payload mock yang realistis ke endpoint. Alat ini berjalan dalam loop sehingga Anda dapat menguji beberapa event dalam satu sesi. Perintah trigger mencakup seluruh 46 jenis event yang dikirim 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.
Payload webhook mock dari dodo wh trigger tidak ditandatangani. Gunakan unsafe_unwrap(), bukan unwrap(), di webhook handler Anda hanya selama pengujian.

CLI Webhook Testing Docs

Lihat dokumentasi lengkap pengujian webhook CLI

Pengaturan Lanjutan

Tab Advanced menyediakan opsi konfigurasi tambahan untuk menyempurnakan perilaku endpoint webhook Anda.

Rate Limiting (Throttling)

Kontrol tingkat pengiriman event webhook ke endpoint Anda untuk mencegah sistem kelebihan beban.
1

Open Advanced Tab

Dari halaman detail endpoint, klik tab Advanced.
2

Configure Rate Limit

Pada bagian “Rate Limit (throttling)”, klik Edit untuk mengubah pengaturan rate limit.
Secara default, webhook tidak memiliki rate limit, sehingga 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 webhook handler Anda memerlukan waktu untuk memproses event atau saat Anda ingin mengelompokkan beberapa event.

Custom Headers

Tambahkan header HTTP khusus ke semua request webhook yang dikirim ke endpoint Anda. Hal ini berguna untuk autentikasi, routing, atau penambahan metadata.
1

Add Headers

Pada bagian “Custom Headers”, masukkan Key dan Value untuk setiap header khusus.
2

Add Multiple Headers

Klik tombol + untuk menambahkan header khusus tambahan sesuai kebutuhan.
Header khusus Anda disertakan dalam semua request webhook ke endpoint ini.

Transformations

Transformation memungkinkan Anda mengubah payload webhook dan, secara opsional, mengalihkannya ke URL lain. Fitur canggih ini memungkinkan Anda untuk:
  • Mengubah struktur payload sebelum diproses
  • Merutekan 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.
Transformation dapat memengaruhi performa pengiriman webhook. Uji secara menyeluruh dan buat logika transformation tetap sederhana serta efisien.
Transformation sangat berguna untuk:
  • Mengonversi berbagai format data
  • Memfilter event berdasarkan kriteria tertentu
  • Menambahkan field hasil perhitungan ke payload
  • Merutekan event ke microservice yang berbeda

Memantau Log Webhook

Tab Logs memberikan 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 bilah pencarian untuk menemukan pesan tertentu berdasarkan ID atau jenis event. Filter berdasarkan status (Succeeded, Failed, Pending, dan sebagainya) untuk fokus pada event yang perlu Anda selidiki.
4

View Message Details

Klik pesan apa pun untuk membuka halaman detail pesan, 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 pesan tersebut tanpa meninggalkan halaman.

Pemantauan Aktivitas

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 bergantung pada rentang waktu. Setiap batang dibagi berdasarkan hasil, dan saat mengarahkan kursor ke suatu segmen, akan ditampilkan status, jumlah upaya, serta bagiannya dari total. Pada endpoint, Delivery stats (last 24h) di tab Overview merangkum informasi yang sama untuk hari terakhir.
Kolom Error rate (24h) pada tab Endpoints memberi tahu Anda secara sekilas endpoint mana yang memerlukan perhatian, sebelum Anda membukanya.

Me-replay 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 upaya tersebut. Anda tidak perlu membuka endpoint.
  • Rentang pesan — buka endpoint, karena mode massal hanya bekerja pada satu endpoint dalam satu waktu.

Replay Massal

Buka endpoint dari Developer → Webhooks. Tersedia tiga mode, dan masing-masing hanya berlaku pada endpoint tersebut. Rentang yang Anda tetapkan bergantung pada mode:
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 tercantum dalam tabel.
3

Start the Run

Klik Recover atau Replay, bergantung pada mode yang Anda pilih.
Setiap proses akan muncul di bawah Replay history pada tab Overview endpoint, lengkap dengan mode, rentang waktu, status, dan jumlah pesan yang dikirim ulang.

Peringatan Email

Terima notifikasi email saat pengiriman webhook ke endpoint gagal, sehingga Anda dapat mengatasi masalah sebelum berubah menjadi backlog.
1

Navigate to Settings Tab

Buka Developer → Webhooks dan buka tab Settings.
2

Find Email Alerting

Temukan kartu Email alerting.
3

Configure Email Addresses

Masukkan alamat yang harus menerima peringatan. Pisahkan beberapa alamat dengan koma, dan biarkan field kosong untuk menonaktifkan peringatan.
4

Save

Klik Save untuk menerapkan perubahan.
Aktifkan peringatan email untuk mendeteksi masalah pengiriman webhook sejak awal dan menjaga integrasi tetap andal.

Deploy ke Cloud Platform

Siap men-deploy webhook handler ke production? Kami menyediakan panduan khusus platform untuk membantu Anda men-deploy webhook ke penyedia cloud populer dengan praktik terbaik untuk setiap platform.

Vercel

Deploy webhook ke Vercel dengan serverless function

Cloudflare Workers

Jalankan webhook di edge network Cloudflare

Supabase Edge Functions

Integrasikan webhook dengan Supabase

Netlify Functions

Deploy webhook sebagai serverless function Netlify
Setiap panduan platform mencakup penyiapan environment, signature verification, dan langkah deployment khusus untuk penyedia tersebut.

Referensi API Terkait

Create Webhook

Referensi API untuk membuat dan mengonfigurasi endpoint webhook secara terprogram

List Webhooks

Referensi API untuk mengambil dan mengelola endpoint webhook Anda
Terakhir diubah pada 8 Agustus 2026