Skip to main content
Gambar Sampul Webhook
Webhook mengirimkan notifikasi real-time saat event terjadi di akun Dodo Payments Anda. Gunakan webhook untuk mengotomatiskan workflow, memperbarui database, mengirim notifikasi, dan menjaga sistem Anda tetap sinkron.
Webhook Dodo Payments mengikuti spesifikasi Standard Webhooks untuk verifikasi signature dan struktur payload.

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

1

Go to Developer → Webhooks

Di Dodo Payments Dashboard, buka Developer → Webhooks.
2

Click Add Endpoint

Klik Add endpoint untuk membuat penerima webhook baru.
3

Enter Your Endpoint URL

Masukkan URL HTTPS tempat Dodo Payments akan mengirimkan event webhook, atau pilih integration connector (Slack, Discord, Zapier, Resend, dan lainnya) untuk meneruskan event ke layanan pihak ketiga tanpa menulis kode.
4

Select Events

Pilih event yang ingin diterima. Event dikelompokkan berdasarkan resource (payment, subscription, dispute, dan lainnya). Anda dapat memilih event individual atau seluruh resource untuk menerima semua event terkait.
5

Save

Klik Create endpoint. Secret signing webhook Anda akan muncul di tab Overview endpoint.
Jaga keamanan secret webhook Anda. Jangan pernah mengeksposnya dalam kode sisi klien atau version control.
Untuk merotasi secret webhook, buka endpoint lalu klik Rotate secret di samping secret pada tab Overview. Secret lama tetap valid selama 24 jam setelah rotasi.

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: Dashboard menampilkan semua connector yang tersedia untuk bisnis Anda. Lihat External Integrations untuk mengetahui tindakan yang dapat dilakukan setiap tujuan terhadap event.

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.
Gunakan connector untuk menjangkau tujuan yang didukung tanpa menulis kode. Jika Anda memerlukan logika khusus, gunakan endpoint standar dengan transformation.

Mengonfigurasi Event yang Di-subscribe

Konfigurasikan event yang diterima setiap endpoint webhook.
1

Navigate to Webhook Endpoints

Buka Developer → Webhooks lalu klik endpoint Anda.
2

Open Event Configuration

Klik Edit untuk membuka side sheet konfigurasi endpoint.
3

Select Events

Pemilih jenis event menampilkan semua event webhook yang tersedia dalam tree yang dapat dicari dan dikelompokkan berdasarkan resource (misalnya, payment, subscription, dispute). Centang kotak di samping event yang ingin diterima. Anda dapat memilih event individual, seluruh resource, atau kombinasi keduanya.
4

Save Configuration

Klik Save untuk menerapkan perubahan.
Jika Anda membatalkan pilihan semua event, endpoint webhook akan menerima setiap jenis event. Pilih hanya event yang diperlukan aplikasi Anda.

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

Telusuri event sebagai dokumentasi referensi yang dikelompokkan berdasarkan resource.

Pengiriman Webhook

Timeout

Webhook memiliki timeout 30 detik untuk operasi koneksi dan pembacaan. Proses webhook secara asinkron dengan segera mengembalikan status code 200, lalu tangani event di latar belakang.

Percobaan Ulang Otomatis

Pengiriman yang gagal akan dicoba ulang dengan exponential backoff, hingga total 8 percobaan: Gunakan dashboard untuk memutar ulang pesan yang gagal secara manual atau memulihkan pesan secara massal dari rentang waktu tertentu.

Idempotensi

Setiap webhook menyertakan header webhook-id yang unik. Simpan ID ini untuk mendeteksi dan melewati event duplikat, karena percobaan ulang dapat mengirimkan event yang sama beberapa kali.
Selalu terapkan pemeriksaan idempotensi. Karena adanya percobaan ulang, Anda mungkin menerima event yang sama beberapa kali.

Urutan Event

Event dapat tiba tidak berurutan karena percobaan ulang atau kondisi jaringan. Setiap webhook menyertakan field timestamp; 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 header webhook-signature: signature HMAC SHA256 dari payload dan timestamp, yang ditandatangani dengan secret key Anda.

Verifikasi SDK (Direkomendasikan)

Semua SDK resmi menyertakan helper bawaan. Tetapkan DODO_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.
Nama metode mengikuti konvensi setiap bahasa: unwrap / unsafeUnwrap dalam TypeScript, unwrap / unsafe_unwrap dalam Python, dan Unwrap / UnsafeUnwrap dalam Go.
Berikan secret webhook Anda melalui DODO_PAYMENTS_WEBHOOK_KEY saat menginisialisasi client Dodo Payments.

Verifikasi Manual (Alternatif)

Jika Anda tidak menggunakan SDK, verifikasi signature sendiri:
  1. 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.
  2. Ambil secret webhook Anda. Jika diawali whsec_, hapus prefix tersebut, lalu lakukan base64-decode pada sisanya untuk mendapatkan signing key.
  3. Hitung HMAC-SHA256 dari konten bertanda tangan menggunakan signing key, lalu lakukan base64-encode pada hasilnya.
  4. Header webhook-signature berisi satu atau beberapa signature yang dipisahkan spasi, masing-masing dalam bentuk v1,<base64-signature>. Request valid jika signature v1 mana pun cocok dengan milik Anda. Bandingkan menggunakan fungsi constant-time.
  5. Tolak request jika webhook-timestamp terlalu jauh dari waktu saat ini untuk mencegah replay attack. Library Standard Webhooks mengizinkan 5 menit.
Lihat library Standard Webhooks untuk implementasi referensi. Untuk format payload event, lihat Webhook Payload.

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 header webhook-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.
Pada platform serverless dan hosting terkelola, pemfilteran IP masuk sering kali tidak tersedia atau tidak praktis. Verifikasi signature adalah kontrol yang tepat di lingkungan tersebut.
Pengiriman yang diblokir dianggap gagal dan akan dicoba ulang sesuai jadwal yang dijelaskan dalam Percobaan Ulang Otomatis. Jika aturan firewall menyebabkan pengiriman gagal, Anda dapat mengirim ulang setelah aturan diperbaiki — lihat Memutar Ulang dan Memulihkan Pesan.

Merespons Webhook

Handler webhook Anda harus mengembalikan 2xx 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-id untuk mendeteksi dan melewati event duplikat.
  • Amankan secret Anda. Simpan DODO_PAYMENTS_WEBHOOK_KEY dalam environment variables atau secrets manager, jangan pernah di version control.

Struktur Payload Webhook

Format Request

string
wajib
Pengenal 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.

Request Body

string
wajib
Pengenal 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

Mengirim Contoh Event

Uji integrasi webhook langsung dari dashboard:
1

Navigate to Webhooks

Buka Developer → Webhooks dan klik endpoint Anda.
2

Open Testing Tab

Klik tab Testing.
3

Send Example

Pilih jenis event dan klik Send example. Payload sampel akan dikirim ke URL endpoint Anda persis seperti event nyata, dengan signature yang sama.
4

Check Your Endpoint

Pastikan event telah tiba, verifikasi signature berhasil, dan Anda mengembalikan status code 2xx.
Pesan yang gagal dikirim dari tab Testing akan dicoba ulang sesuai jadwal percobaan ulang normal, seperti webhook lainnya.

Contoh Implementasi

Implementasi Express.js lengkap dengan verifikasi dan penanganan webhook:
Uji handler webhook Anda secara menyeluruh menggunakan antarmuka pengujian dashboard sebelum memproses event production. Ini membantu mengidentifikasi dan memperbaiki masalah sejak awal.

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:
CLI membuka koneksi WebSocket dan meneruskan setiap event webhook ke endpoint lokal Anda (misalnya, http://localhost:3000/webhook), dengan mempertahankan semua header untuk pengujian verifikasi signature.
Listener hanya berfungsi dengan API key test mode. Jalankan dodo login dan pilih Test Mode terlebih dahulu.

Memicu Event Mock Webhook

Kirim payload webhook mock ke endpoint mana pun tanpa membuat transaksi nyata:
Tool interaktif ini memungkinkan Anda memilih jenis event dan mengirim payload mock yang realistis ke endpoint Anda. Tool ini berjalan dalam loop sehingga Anda dapat menguji beberapa event dalam satu sesi. Perintah trigger mencakup kelompok subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, dan entitlement grant. Perintah ini tidak mengirim subscription.past_due atau subscription.unpaused. Lihat Supported Webhook Events untuk daftar lengkapnya.
Payload webhook mock dari dodo wh trigger tidak memiliki signature. Gunakan metode penguraian tanpa verifikasi (unsafeUnwrap dalam TypeScript, unsafe_unwrap dalam Python, UnsafeUnwrap dalam Go) 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.

Pembatasan Rate (Throttling)

Kontrol laju pengiriman event webhook ke endpoint Anda. Secara default, webhook tidak memiliki rate limit dan event dikirim segera setelah terjadi.
1

Open Advanced Tab

Dari halaman detail endpoint, klik tab Advanced.
2

Configure Rate Limit

Buka bagian Endpoint throttling.
3

Set Your Limit

Masukkan jumlah maksimum pesan per detik, lalu klik Save. Pengiriman yang melebihi laju ini akan dimasukkan ke antrean, bukan dibuang.

Header Kustom

Tambahkan header HTTP kustom ke semua request webhook yang dikirim ke endpoint Anda. Berguna untuk autentikasi, routing, atau penambahan metadata.
1

Add Headers

Di bagian Custom headers, masukkan nama dan nilai header.
2

Add Multiple Headers

Klik Add header untuk setiap header tambahan, lalu klik Save.

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
1

Enable Transformations

Di bagian Transformation, aktifkan Enable transformation.
2

Configure Transformation

Tulis aturan transformasi dalam JavaScript di code editor, lalu klik Save. Kode harus mengembalikan objek webhook dari handler().
3

Test Transformation

Gunakan antarmuka pengujian transformasi untuk memastikan transformasi Anda berfungsi dengan benar sebelum digunakan.
Transformasi dapat memengaruhi performa pengiriman webhook. Uji secara menyeluruh dan buat logika transformasi tetap sederhana serta efisien.

Memantau Log Webhook

Tab Logs memberikan visibilitas terhadap status pengiriman webhook Anda.
1

Navigate to Logs Tab

Buka Developer → Webhooks dan buka tab Logs.
2

Browse Delivery History

Lihat tabel semua percobaan 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 mana pun untuk membuka halaman detail pesan, yang menampilkan:
  • Payload webhook lengkap
  • Setiap percobaan pengiriman dengan response code dan durasi
  • Timestamp setiap percobaan
  • Pesan error apa pun dari endpoint Anda
Setiap percobaan memiliki tindakan Replay untuk 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 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.
Kolom Error rate (24h) di tab Endpoints menunjukkan endpoint mana yang memerlukan perhatian secara sekilas.

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:
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 mode tersebut, seperti tercantum dalam tabel.
3

Start the Run

Klik Recover atau Replay, sesuai mode yang Anda pilih.
Setiap proses muncul di bagian Replay history pada tab Overview endpoint, beserta mode, rentang waktu, status, dan jumlah pesan yang dikirim ulang.

Peringatan Email

Dashboard webhook tidak menyediakan peringatan email untuk pengiriman yang gagal. Untuk memantau pengiriman, buka Developer → Webhooks dan periksa tab Logs serta Activity.

Deploy ke Platform Cloud

Panduan khusus platform untuk men-deploy handler webhook ke penyedia cloud populer:

Vercel

Deploy webhook ke Vercel dengan fungsi serverless

Cloudflare Workers

Jalankan webhook di jaringan edge Cloudflare

Supabase Edge Functions

Integrasikan webhook dengan Supabase

Netlify Functions

Deploy webhook sebagai fungsi serverless Netlify

Referensi API Terkait

Create Webhook

Buat dan konfigurasikan endpoint webhook secara terprogram

List Webhooks

Ambil dan kelola endpoint webhook Anda
Terakhir diubah pada 26 September 2026