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.

Alamat IP Sumber

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.

Merespons Webhook

  • Handler webhook Anda harus mengembalikan 2xx status code untuk mengakui penerimaan event.
  • Respons lainnya akan diperlakukan 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 idempotency menggunakan header webhook-id agar event yang sama dapat diproses beberapa kali dengan aman tanpa efek samping.
Simpan webhook secret Anda dengan aman menggunakan environment variables atau secrets manager. Jangan pernah commit secret ke version control.

Struktur Payload Webhook

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

Format Request

Headers

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

Request Body

string
wajib
Business identifier 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

Jelajahi semua jenis event webhook yang tersedia

Event Payloads

Lihat schema 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 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.

Mengirim Contoh Event

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.

Contoh Implementasi

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

Menguji Webhook dengan CLI

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

Mendengarkan Webhook Live Secara Lokal

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

Memicu Mock Webhook Event

Kirim mock webhook payload ke endpoint mana pun tanpa membuat transaksi nyata:
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.

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 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.

Custom Headers

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

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.
Transformations sangat berguna untuk:
  • Mengonversi berbagai format data
  • Memfilter event berdasarkan kriteria tertentu
  • Menambahkan field terhitung ke payload
  • Mengarahkan event ke microservice yang berbeda

Memantau Log Webhook

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.

Memantau 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 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.

Memutar Ulang dan Memulihkan Message

Cara Anda mengirim ulang message bergantung pada jumlah message yang diperlukan:
  • Satu message — buka dari tab Logs dan gunakan tindakan Replay pada upaya tersebut. Anda tidak perlu membuka endpoint.
  • Rentang message — buka endpoint, karena mode bulk hanya bekerja pada satu endpoint dalam satu waktu.

Memutar Ulang Secara Bulk

Buka endpoint dari Developer → Webhooks. Tersedia tiga mode, dan masing-masing hanya berlaku untuk 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 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.

Email Alerts

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

Navigate to Settings Tab

Buka Developer → Webhooks dan buka tab Settings.
2

Find Email Alerting

Temukan card Email alerting.
3

Configure Email Addresses

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

Save

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

Deploy ke Cloud Platform

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.

Referensi API Terkait

Create Webhook

Referensi API untuk membuat dan mengonfigurasi endpoint webhook secara programatis

List Webhooks

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