Langsung ke konten utama
Gambar Sampul Webhook
Webhooks memberikan notifikasi waktu nyata saat peristiwa tertentu terjadi di akun Dodo Payments Anda. Gunakan webhooks untuk mengotomatiskan alur kerja, memperbarui basis data Anda, mengirim notifikasi, dan menjaga sistem Anda tetap sinkron.
Implementasi webhook kami mengikuti spesifikasi Standard Webhooks, memastikan kompatibilitas dengan praktik terbaik industri dan pustaka webhook yang ada.

Fitur Utama

Pengiriman Waktu Nyata

Terima notifikasi instan saat peristiwa terjadi

Aman Secara Default

Verifikasi tanda tangan HMAC SHA256 termasuk

Pengulangan Otomatis

Logika pengulangan bawaan dengan backoff eksponensial

Penyaringan Peristiwa

Berlangganan hanya pada peristiwa yang Anda butuhkan

Memulai

1

Akses Pengaturan Webhook

Navigasikan ke Dasbor DodoPayments dan pergi ke Settings > Webhooks.
2

Buat Endpoint Webhook

Klik pada Add Webhook untuk membuat endpoint webhook baru.
Tambahkan Webhook
3

Tambahkan URL Endpoint

Masukkan URL tempat Anda ingin menerima peristiwa webhook.
4

Pilih Peristiwa untuk Diterima

Pilih peristiwa spesifik yang harus didengarkan oleh endpoint webhook Anda dengan memilihnya dari daftar peristiwa.
Hanya peristiwa yang dipilih yang akan memicu webhook ke endpoint Anda, membantu Anda menghindari lalu lintas dan pemrosesan yang tidak perlu.
5

Dapatkan Kunci Rahasia

Dapatkan Secret Key webhook Anda dari halaman pengaturan. Anda akan menggunakan ini untuk memverifikasi keaslian webhook yang diterima.
Jaga kunci rahasia webhook Anda dengan aman dan jangan pernah mengeksposnya dalam kode sisi klien atau repositori publik.
6

Putar Rahasia (Opsional)

Jika perlu, Anda dapat memutar rahasia webhook Anda untuk meningkatkan keamanan. Klik tombol Putar Rahasia di pengaturan webhook Anda.
Memutar rahasia akan mengakhiri dan menggantinya dengan yang baru. Rahasia lama hanya akan berlaku selama 24 jam ke depan. Setelah itu, mencoba memverifikasi dengan rahasia lama akan gagal.
Gunakan rotasi rahasia secara berkala atau segera jika Anda mencurigai rahasia Anda saat ini telah dikompromikan.

Mengonfigurasi Peristiwa yang Didaftarkan

Anda dapat mengonfigurasi peristiwa spesifik yang ingin mereka terima untuk setiap endpoint webhook.

Mengakses Konfigurasi Peristiwa

1

Navigasikan ke Detail Webhook

Pergi ke Dasbor Dodo Payments Anda dan navigasikan ke Settings > Webhooks.
2

Pilih Endpoint Anda

Klik pada endpoint webhook yang ingin Anda konfigurasi.
3

Buka Pengaturan Peristiwa

Di halaman detail webhook, Anda akan melihat bagian “Peristiwa yang Didaftarkan”. Klik tombol Edit untuk memodifikasi langganan peristiwa Anda.

Mengelola Langganan Peristiwa

1

Lihat Peristiwa yang Tersedia

Antarmuka menampilkan semua peristiwa webhook yang tersedia yang diorganisir dalam struktur hierarkis. Peristiwa dikelompokkan berdasarkan kategori (misalnya, dispute, payment, subscription).
2

Cari dan Saring

Gunakan bilah pencarian untuk dengan cepat menemukan peristiwa tertentu dengan mengetikkan nama peristiwa atau kata kunci.
3

Pilih Peristiwa

Centang kotak di sebelah peristiwa yang ingin Anda terima. Anda dapat:
  • Memilih sub-peristiwa individu (misalnya, dispute.accepted, dispute.challenged)
  • Memilih peristiwa induk untuk menerima semua sub-peristiwa terkait
  • Menggabungkan dan mencocokkan peristiwa spesifik berdasarkan kebutuhan Anda
4

Tinjau Detail Peristiwa

Arahkan kursor ke ikon informasi (ⓘ) di sebelah setiap peristiwa untuk melihat deskripsi tentang kapan peristiwa tersebut dipicu.
5

Simpan Konfigurasi

Klik Simpan untuk menerapkan perubahan Anda, atau Batal untuk membatalkan modifikasi.
Jika Anda membatalkan semua peristiwa, endpoint webhook Anda tidak akan menerima notifikasi apa pun. Pastikan untuk memilih setidaknya peristiwa yang dibutuhkan aplikasi Anda untuk berfungsi dengan baik.

Pengiriman Webhook

Timeout

Webhook memiliki jendela timeout 15 detik untuk operasi koneksi dan baca. Pastikan endpoint Anda merespons dengan cepat untuk menghindari timeout.
Proses webhook secara asinkron dengan mengakui penerimaan segera dengan kode status 200, lalu menangani pemrosesan yang sebenarnya di latar belakang.

Pengulangan Otomatis

Jika pengiriman webhook gagal, Dodo Payments secara otomatis mencoba ulang dengan backoff eksponensial untuk mencegah sistem Anda kewalahan.
UpayaPenundaanDeskripsi
1SegeraPengulangan pertama terjadi segera
25 detikUpaya kedua setelah penundaan singkat
35 menitUpaya ketiga dengan backoff yang meningkat
430 menitUpaya keempat melanjutkan backoff
52 jamUpaya kelima dengan penundaan yang diperpanjang
65 jamUpaya keenam dengan penundaan yang lebih lama
710 jamUpaya ketujuh dengan penundaan maksimum
810 jamUpaya terakhir - webhook ditandai sebagai gagal jika tidak berhasil
Maksimum 8 upaya pengulangan per peristiwa webhook. Misalnya, jika sebuah webhook gagal tiga kali sebelum berhasil, total waktu pengiriman adalah sekitar 35 menit dan 5 detik dari upaya pertama.
Gunakan dasbor Dodo Payments untuk mencoba ulang pesan individu secara manual atau memulihkan semua pesan yang gagal secara massal kapan saja.

Idempotensi

Setiap peristiwa webhook menyertakan header webhook-id yang unik. Gunakan pengidentifikasi ini untuk menerapkan idempotensi dan mencegah pemrosesan duplikat.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
Selalu terapkan pemeriksaan idempotensi. Karena pengulangan, Anda mungkin menerima peristiwa yang sama beberapa kali.

Urutan Peristiwa

Peristiwa webhook mungkin tiba tidak teratur karena pengulangan atau kondisi jaringan. Rancang sistem Anda untuk menangani peristiwa dalam urutan apa pun.
Anda akan menerima payload terbaru pada saat pengiriman, terlepas dari kapan peristiwa webhook awalnya dipancarkan.

Mengamankan Webhooks

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

Memverifikasi Tanda Tangan

Setiap permintaan webhook menyertakan header webhook-signature, tanda tangan HMAC SHA256 dari payload webhook dan timestamp, ditandatangani dengan kunci rahasia Anda.

Verifikasi SDK (disarankan)

Semua SDK resmi menyertakan pembantu bawaan untuk memvalidasi dan mengurai webhook yang masuk dengan aman. Dua metode tersedia:
  • unwrap(): Memverifikasi tanda tangan menggunakan kunci rahasia webhook Anda
  • unsafe_unwrap(): Mengurai payload tanpa verifikasi
Berikan rahasia webhook Anda melalui DODO_PAYMENTS_WEBHOOK_KEY saat menginisialisasi klien Dodo Payments.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Verifikasi Manual (alternatif)

Jika Anda tidak menggunakan SDK, Anda dapat memverifikasi tanda tangan sendiri mengikuti spesifikasi Standard Webhooks:
  1. Bangun pesan yang ditandatangani dengan menggabungkan webhook-id, webhook-timestamp, dan string mentah yang tepat payload, dipisahkan oleh titik (.).
  2. Hitung HMAC SHA256 dari string tersebut menggunakan kunci rahasia webhook Anda dari Dasbor.
  3. Bandingkan tanda tangan yang dihitung dengan header webhook-signature. Jika cocok, webhook tersebut asli.
Kami mengikuti spesifikasi Standard Webhooks. Anda dapat menggunakan pustaka mereka untuk memverifikasi tanda tangan: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Untuk format payload peristiwa, lihat Payload Webhook.

Menanggapi Webhooks

  • Penangan webhook Anda harus mengembalikan 2xx status code untuk mengakui penerimaan peristiwa.
  • Respon lainnya akan dianggap sebagai kegagalan, dan webhook akan dicoba ulang.

Praktik Terbaik

Selalu gunakan URL HTTPS untuk endpoint webhook. Endpoint HTTP rentan terhadap serangan man-in-the-middle dan mengekspos data webhook Anda.
Kembalikan kode status 200 segera setelah menerima webhook. Proses peristiwa secara asinkron untuk menghindari timeout.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Terapkan idempotensi menggunakan header webhook-id untuk memproses peristiwa yang sama beberapa kali tanpa efek samping.
Simpan rahasia webhook Anda dengan aman menggunakan variabel lingkungan atau pengelola rahasia. Jangan pernah mengkomit rahasia ke kontrol versi.

Struktur Payload Webhook

Memahami struktur payload webhook membantu Anda mengurai dan memproses peristiwa dengan benar.

Format Permintaan

POST /your-webhook-url
Content-Type: application/json
webhook-id
string
required
Pengidentifikasi unik untuk peristiwa webhook ini. Gunakan ini untuk pemeriksaan idempotensi.
webhook-signature
string
required
Tanda tangan HMAC SHA256 untuk memverifikasi keaslian webhook.
webhook-timestamp
string
required
Timestamp Unix (dalam detik) saat webhook dikirim.

Body Permintaan

business_id
string
required
Pengidentifikasi bisnis Dodo Payments Anda.
type
string
required
Tipe peristiwa yang memicu webhook ini (misalnya, payment.succeeded, subscription.created).
timestamp
string
required
Timestamp yang diformat ISO 8601 tentang kapan peristiwa terjadi.
data
object
required
Payload spesifik peristiwa yang berisi informasi rinci tentang peristiwa.

Contoh Payload

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

Menguji Webhooks

Anda dapat menguji integrasi webhook Anda langsung dari dasbor Dodo Payments untuk memastikan endpoint Anda berfungsi dengan benar sebelum diluncurkan.
Detail Endpoint

Mengakses Antarmuka Pengujian

1

Navigasikan ke Webhooks

Pergi ke Dasbor Dodo Payments Anda dan navigasikan ke Settings > Webhooks.
2

Pilih Endpoint Anda

Klik pada endpoint webhook Anda untuk mengakses halaman detailnya.
3

Buka Tab Pengujian

Klik pada tab Pengujian untuk mengakses antarmuka pengujian webhook.

Menguji Webhook Anda

Antarmuka pengujian menyediakan cara komprehensif untuk menguji endpoint webhook Anda:
1

Pilih Tipe Peristiwa

Gunakan menu dropdown untuk memilih tipe peristiwa spesifik yang ingin Anda uji (misalnya, payment.succeeded, payment.failed, dll.).
Dropdown berisi semua tipe peristiwa webhook yang tersedia yang dapat diterima oleh endpoint Anda.
2

Tinjau Skema dan Contoh

Antarmuka menampilkan baik Skema (struktur data) dan Contoh (payload sampel) untuk tipe peristiwa yang dipilih.
3

Kirim Peristiwa Uji

Klik tombol Kirim Contoh untuk mengirim webhook uji ke endpoint Anda.
Penting: Pesan yang gagal yang dikirim melalui antarmuka pengujian tidak akan dicoba ulang. Ini hanya untuk tujuan pengujian.

Memverifikasi Uji Anda

1

Periksa Endpoint Anda

Pantau log endpoint webhook Anda untuk mengonfirmasi bahwa peristiwa uji diterima.
2

Verifikasi Tanda Tangan

Pastikan verifikasi tanda tangan Anda berfungsi dengan benar dengan payload uji.
3

Uji Respon

Konfirmasi bahwa endpoint Anda mengembalikan kode status 2xx untuk mengakui penerimaan.

Contoh Implementasi

Berikut adalah implementasi lengkap Express.js yang menunjukkan verifikasi dan penanganan webhook:
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
app.use(express.json());

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
Uji penangan webhook Anda secara menyeluruh menggunakan antarmuka pengujian dasbor sebelum memproses peristiwa produksi. Ini membantu mengidentifikasi dan memperbaiki masalah lebih awal.

Pengaturan Lanjutan

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

Pembatasan Laju (Throttling)

Kontrol laju di mana peristiwa webhook dikirim ke endpoint Anda untuk mencegah sistem Anda kewalahan.
1

Akses Pengaturan Pembatasan Laju

Di tab Lanjutan, temukan bagian “Pembatasan Laju (throttling)”.
2

Konfigurasi Pembatasan Laju

Klik tombol Edit untuk memodifikasi pengaturan pembatasan laju.
Secara default, webhook memiliki “Tidak ada pembatasan laju” yang diterapkan, yang berarti peristiwa dikirim segera setelah terjadi.
3

Tetapkan Batas

Konfigurasikan batas laju yang Anda inginkan untuk mengontrol frekuensi pengiriman webhook dan mencegah kelebihan beban sistem.
Gunakan pembatasan laju ketika penangan webhook Anda membutuhkan waktu untuk memproses peristiwa atau ketika Anda ingin menggabungkan beberapa peristiwa bersama-sama.

Header Kustom

Tambahkan header HTTP kustom ke semua permintaan webhook yang dikirim ke endpoint Anda. Ini berguna untuk otentikasi, pengalihan, atau menambahkan metadata ke permintaan webhook Anda.
1

Tambahkan Header Kustom

Di bagian “Header Kustom”, masukkan Kunci dan Nilai untuk header kustom Anda.
2

Tambahkan Beberapa Header

Klik tombol + untuk menambahkan header kustom tambahan sesuai kebutuhan.
3

Simpan Konfigurasi

Header kustom Anda akan disertakan dalam semua permintaan webhook ke endpoint ini.

Transformasi

Transformasi memungkinkan Anda untuk memodifikasi payload webhook dan mengarahkannya ke URL yang berbeda. Fitur kuat ini memungkinkan Anda untuk:
  • Memodifikasi struktur payload sebelum pemrosesan
  • Mengarahkan webhook ke endpoint yang berbeda berdasarkan konten
  • Menambahkan atau menghapus bidang dari payload
  • Mengubah format data
1

Aktifkan Transformasi

Alihkan sakelar Diaktifkan untuk mengaktifkan fitur transformasi.
2

Konfigurasi Transformasi

Klik Edit transformasi untuk mendefinisikan aturan transformasi Anda.
Anda dapat menggunakan JavaScript untuk mentransformasi payload webhook dan menentukan URL target yang berbeda.
3

Uji Transformasi

Gunakan antarmuka pengujian untuk memverifikasi bahwa transformasi Anda berfungsi dengan benar sebelum diluncurkan.
Transformasi dapat secara signifikan mempengaruhi kinerja pengiriman webhook. Uji secara menyeluruh dan jaga logika transformasi tetap sederhana dan efisien.
Transformasi sangat berguna untuk:
  • Mengonversi antara format data yang berbeda
  • Menyaring peristiwa berdasarkan kriteria tertentu
  • Menambahkan bidang yang dihitung ke payload
  • Mengarahkan peristiwa ke mikroservis yang berbeda

Memantau Log Webhook

Tab Log memberikan visibilitas komprehensif ke dalam status pengiriman webhook Anda, memungkinkan Anda untuk memantau, melakukan debug, dan mengelola peristiwa webhook secara efektif.
Log

Pemantauan Aktivitas

Tab Aktivitas memberikan wawasan waktu nyata ke dalam kinerja pengiriman webhook Anda dengan analitik visual.
Aktivitas

Pemberitahuan Email

Tetap terinformasi tentang kesehatan webhook Anda dengan notifikasi email otomatis. Ketika pengiriman webhook mulai gagal atau endpoint Anda berhenti merespons, Anda akan menerima pemberitahuan email sehingga Anda dapat dengan cepat menangani masalah dan menjaga integrasi Anda tetap berjalan lancar.
Pengaturan Pemberitahuan Webhook menunjukkan konfigurasi notifikasi email

Aktifkan Pemberitahuan Email

1

Navigasikan ke Pengaturan Pemberitahuan

Pergi ke Dasbor Dodo Payments Anda dan navigasikan ke Dasbor → Webhooks → Pemberitahuan.
2

Aktifkan Notifikasi Email

Alihkan Notifikasi email untuk mulai menerima pemberitahuan tentang masalah pengiriman webhook.
3

Konfigurasi Alamat Email

Masukkan alamat email tempat Anda ingin menerima pemberitahuan webhook. Kami akan mengirimkan notifikasi ke alamat ini ketika peristiwa tertentu terjadi dengan pengaturan webhook Anda, seperti masalah pengiriman yang mungkin mempengaruhi integrasi Anda.
Aktifkan pemberitahuan email untuk menangkap masalah pengiriman webhook lebih awal dan menjaga integrasi yang dapat diandalkan. Anda akan diberitahu ketika pengiriman gagal atau endpoint Anda menjadi tidak responsif.

Deploy ke Platform Cloud

Siap untuk menerapkan penangan webhook Anda ke produksi? Kami menyediakan panduan spesifik platform untuk membantu Anda menerapkan webhook ke penyedia cloud populer dengan praktik terbaik untuk setiap platform.
Setiap panduan platform mencakup pengaturan lingkungan, verifikasi tanda tangan, dan langkah-langkah penerapan yang spesifik untuk penyedia tersebut.