Langsung ke konten utama
Webhook Cover Image
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 sudah ada.

Fitur Utama

Real-time Delivery

Terima notifikasi instan ketika peristiwa terjadi

Secure by Default

Pemeriksaan tanda tangan HMAC SHA256 disertakan

Automatic Retries

Logika percobaan ulang bawaan dengan exponential backoff

Event Filtering

Berlangganan hanya pada peristiwa yang Anda perlukan

Memulai

1

Access Webhook Settings

Arahkan ke Dasbor DodoPayments dan buka Settings > Webhooks.
2

Create Webhook Endpoint

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

Add Endpoint URL

Masukkan URL tempat Anda ingin menerima peristiwa webhook.
4

Select Events to Receive

Pilih peristiwa spesifik yang harus didengarkan 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

Get Secret Key

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

Rotate Secret (Optional)

Jika perlu, Anda dapat mengganti rahasia webhook untuk keamanan yang lebih baik. Klik tombol Rotate Secret di pengaturan webhook Anda.
Mengganti rahasia akan menghentikan yang lama dan menggantikannya dengan yang baru. Rahasia lama hanya akan valid selama 24 jam berikutnya. Setelah itu, mencoba memverifikasi dengan rahasia lama akan gagal.
Gunakan rotasi rahasia secara berkala atau segera jika Anda mencurigai rahasia 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

Navigate to Webhook Details

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

Select Your Endpoint

Klik endpoint webhook yang ingin Anda konfigurasikan.
3

Open Event Settings

Di halaman detail webhook, Anda akan melihat bagian “Subscribed events”. Klik tombol Edit untuk memodifikasi langganan peristiwa Anda.

Mengelola Langganan Peristiwa

1

View Available Events

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

Search and Filter

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

Select Events

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

Review Event Details

Arahkan kursor ke ikon informasi (ⓘ) di samping setiap peristiwa untuk melihat deskripsi kapan peristiwa itu dipicu.
5

Save Configuration

Klik Save untuk menerapkan perubahan Anda, atau Cancel untuk membatalkan modifikasi.
Jika Anda membatalkan pilihan semua peristiwa, endpoint webhook Anda tidak akan menerima notifikasi apa pun. Pastikan untuk memilih setidaknya peristiwa yang dibutuhkan aplikasi Anda agar dapat 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 menggunakan kode status 200, lalu menangani pemrosesan aktual 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
Maksimal 8 percobaan ulang per peristiwa webhook. Misalnya, jika webhook gagal tiga kali sebelum berhasil, total waktu pengiriman sekitar 35 menit 5 detik dari percobaan pertama.
Gunakan dasbor Dodo Payments untuk mencoba ulang pesan secara manual atau memulihkan semua pesan yang gagal secara massal kapan pun.

Idempotensi

Each webhook event includes a unique webhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
// 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 percobaan ulang, 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 diterbitkan.

Mengamankan Webhooks

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

Memverifikasi Tanda Tangan

Each webhook request includes a webhook-signature header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key.

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 payload yang persis, 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 otentik.
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 Webhook Payload.

Menanggapi Webhooks

  • Handler webhook Anda harus mengembalikan kode status 2xx status code untuk mengakui penerimaan peristiwa.
  • Respons lain 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 agar tidak melewati batas waktu.
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
wajib
Identitas unik untuk peristiwa webhook ini. Gunakan ini untuk pemeriksaan idempotensi.
webhook-signature
string
wajib
Tanda tangan HMAC SHA256 untuk memverifikasi keaslian webhook.
webhook-timestamp
string
wajib
Timestamp Unix (dalam detik) saat webhook dikirim.

Body Permintaan

business_id
string
wajib
Identifier bisnis Dodo Payments Anda.
type
string
wajib
Jenis acara yang memicu webhook ini (misalnya payment.succeeded, subscription.active).
timestamp
string
wajib
Timestamp berformat ISO 8601 saat peristiwa terjadi.
data
object
wajib
Payload khusus peristiwa yang berisi informasi rinci tentang peristiwa tersebut.

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

Mengakses Antarmuka Pengujian

1

Navigate to Webhooks

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

Select Your Endpoint

Klik endpoint webhook Anda untuk mengakses halaman detailnya.
3

Open Testing Tab

Klik tab Testing untuk mengakses antarmuka pengujian webhook.

Menguji Webhook Anda

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

Select Event Type

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 endpoint Anda.
2

Review Schema and Example

Antarmuka menampilkan baik Schema (struktur data) maupun Example (payload contoh) untuk tipe peristiwa yang dipilih.
3

Send Test Event

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

Memverifikasi Uji Anda

1

Check Your Endpoint

Pantau log endpoint webhook Anda untuk memastikan peristiwa uji telah diterima.
2

Verify Signature

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

Test Response

Konfirmasi 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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
Uji handler webhook Anda secara menyeluruh menggunakan antarmuka pengujian dasbor sebelum memproses peristiwa produksi. Ini membantu mengidentifikasi dan memperbaiki masalah lebih awal.

Menguji Webhook dengan CLI

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

Mendengarkan Webhook Langsung Secara Lokal

Teruskan peristiwa webhook nyata dari akun mode uji Anda ke server pengembangan lokal Anda secara real time:
dodo wh listen
CLI membuka koneksi WebSocket ke Dodo Payments dan meneruskan setiap peristiwa webhook ke endpoint lokal Anda (misalnya http://localhost:3000/webhook), mempertahankan semua header termasuk header tanda tangan untuk pengujian verifikasi.
Pendengar hanya bekerja dengan kunci API mode uji. Jalankan dodo login dan pilih Mode Uji sebelum menggunakan perintah ini.

Memicu Peristiwa Webhook Tiruan

Kirim payload webhook tiruan ke endpoint mana pun tanpa membuat transaksi nyata:
dodo wh trigger
Alat interaktif ini memungkinkan Anda memilih dari semua 22 tipe peristiwa yang didukung dan mengirim payload tiruan yang realistis ke endpoint Anda. Ia berulang sehingga Anda dapat menguji beberapa peristiwa dalam satu sesi.
Payload webhook tiruan dari dodo wh trigger tidak ditandatangani. Gunakan unsafe_unwrap() alih-alih unwrap() di handler webhook Anda hanya selama pengujian.

CLI Webhook Testing Docs

Lihat dokumentasi lengkap pengujian webhook CLI

Pengaturan Lanjutan

Tab Pengaturan Lanjutan menyediakan opsi konfigurasi tambahan untuk menyetel perilaku endpoint webhook Anda secara halus.

Pembatasan Laju (Throttling)

Kontrol laju pengiriman peristiwa webhook ke endpoint Anda untuk mencegah sistem Anda kewalahan.
1

Access Rate Limit Settings

Di tab Advanced, temukan bagian “Rate Limit (throttling)”.
2

Configure Rate Limit

Klik tombol Edit untuk mengubah pengaturan batas laju.
Secara default, webhook memiliki “No rate limit” yang berarti peristiwa dikirimkan segera setelah terjadi.
3

Set Limits

Konfigurasikan batas laju yang Anda inginkan untuk mengendalikan frekuensi pengiriman webhook dan mencegah sistem kelebihan beban.
Gunakan pembatasan laju ketika handler webhook Anda membutuhkan waktu untuk memproses peristiwa atau ketika Anda ingin menggabungkan beberapa peristiwa.

Header Kustom

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

Add Custom Header

Di bagian “Custom Headers”, masukkan Key dan Value untuk header kustom Anda.
2

Add Multiple Headers

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

Save Configuration

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

Transformasi

Transformasi memungkinkan Anda memodifikasi payload webhook dan mengarahkannya ke URL berbeda. Fitur kuat ini memungkinkan Anda untuk:
  • Mengubah struktur payload sebelum diproses
  • Mengarahkan webhook ke endpoint berbeda berdasarkan isi
  • Menambahkan atau menghapus field dari payload
  • Mengubah format data
1

Enable Transformations

Aktifkan sakelar Enabled untuk mengaktifkan fitur transformasi.
2

Configure Transformation

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

Test Transformation

Gunakan antarmuka pengujian untuk memverifikasi transformasi Anda bekerja dengan baik sebelum digunakan secara langsung.
Transformasi dapat berdampak signifikan pada kinerja pengiriman webhook. Uji secara menyeluruh dan pertahankan logika transformasi tetap sederhana dan efisien.
Transformasi sangat berguna untuk:
  • Mengonversi antar format data yang berbeda
  • Memfilter peristiwa berdasarkan kriteria tertentu
  • Menambahkan field yang dihitung ke payload
  • Mengarahkan peristiwa ke layanan mikro yang berbeda

Memantau Log Webhook

Tab Logs menyediakan visibilitas komprehensif terhadap status pengiriman webhook Anda, memungkinkan Anda memantau, mendebug, dan mengelola peristiwa webhook secara efektif.
Logs

Pemantauan Aktivitas

Tab Activity menyediakan wawasan waktu nyata tentang kinerja pengiriman webhook Anda dengan analitik visual.
Activity

Peringatan Email

Tetap mendapat informasi tentang kesehatan webhook Anda dengan notifikasi email otomatis. Ketika pengiriman webhook mulai gagal atau endpoint Anda berhenti merespons, Anda akan menerima peringatan email agar bisa segera menangani masalah dan menjaga integrasi tetap berjalan lancar.
Webhook Alerting Settings showing email notifications configuration

Mengaktifkan Peringatan Email

1

Navigate to Alerting Settings

Buka Dashboard Dodo Payments Anda dan arahkan ke Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Aktifkan Email notifications untuk mulai menerima notifikasi tentang masalah pengiriman webhook.
3

Configure Email Address

Masukkan alamat email tempat Anda ingin menerima peringatan webhook. Kami akan mengirim notifikasi ke alamat ini ketika terjadi peristiwa tertentu pada pengaturan webhook Anda, seperti masalah pengiriman yang dapat memengaruhi integrasi Anda.
Aktifkan peringatan email untuk mendeteksi masalah pengiriman webhook sejak dini dan menjaga integrasi tetap dapat diandalkan. Anda akan diberitahu ketika pengiriman gagal atau endpoint Anda menjadi tidak responsif.

Menyebarkan ke Platform Cloud

Siap menyebarkan handler webhook Anda ke produksi? Kami menyediakan panduan khusus platform untuk membantu Anda menyebarkan webhook ke penyedia cloud populer dengan praktik terbaik untuk setiap platform.
Setiap panduan platform mencakup pengaturan lingkungan, verifikasi tanda tangan, dan langkah penyebaran khusus penyedia tersebut.