Chuyển đến nội dung chính
Ảnh bìa Webhook
Webhooks cung cấp thông báo theo thời gian thực khi các sự kiện cụ thể xảy ra trong tài khoản Dodo Payments của bạn. Sử dụng webhooks để tự động hóa quy trình làm việc, cập nhật cơ sở dữ liệu của bạn, gửi thông báo và giữ cho hệ thống của bạn đồng bộ.
Việc triển khai webhook của chúng tôi tuân theo đặc tả Standard Webhooks, đảm bảo tương thích với các thực hành tốt nhất trong ngành và các thư viện webhook hiện có.

Tính năng chính

Real-time Delivery

Nhận thông báo ngay khi các sự kiện xảy ra

Secure by Default

Bao gồm xác minh chữ ký HMAC SHA256

Automatic Retries

Logic thử lại tích hợp với độ trễ tăng dần theo cấp số nhân

Event Filtering

Đăng ký chỉ những sự kiện bạn cần

Bắt đầu

1

Access Webhook Settings

Đi đến Bảng điều khiển DodoPayments và chuyển đến Settings > Webhooks.
2

Create Webhook Endpoint

Nhấp vào Add Webhook để tạo một endpoint webhook mới.
Thêm Webhook
3

Add Endpoint URL

Nhập URL nơi bạn muốn nhận các sự kiện webhook.
4

Select Events to Receive

Chọn các sự kiện cụ thể mà endpoint webhook của bạn nên lắng nghe bằng cách chọn chúng từ danh sách sự kiện.
Chỉ các sự kiện được chọn mới kích hoạt webhook đến endpoint của bạn, giúp bạn tránh lưu lượng và xử lý không cần thiết.
5

Get Secret Key

Lấy Secret Key của webhook từ trang cài đặt. Bạn sẽ sử dụng giá trị này để xác minh tính xác thực của các webhook nhận được.
Giữ khóa bí mật webhook an toàn và không bao giờ tiết lộ nó trong mã phía khách hàng hoặc kho lưu trữ công khai.
6

Rotate Secret (Optional)

Nếu cần, bạn có thể thay đổi khóa bí mật webhook để tăng cường bảo mật. Nhấp vào nút Rotate Secret trong cài đặt webhook của bạn.
Việc thay đổi khóa bí mật sẽ hết hạn khóa cũ và thay thế bằng khóa mới. Khóa cũ chỉ còn hiệu lực trong 24 giờ tiếp theo. Sau thời gian đó, việc xác minh bằng khóa cũ sẽ thất bại.
Hãy sử dụng việc thay đổi khóa định kỳ hoặc ngay khi bạn nghi ngờ khóa hiện tại bị xâm phạm.

Cấu hình Sự kiện Đăng ký

Bạn có thể cấu hình các sự kiện cụ thể mà họ muốn nhận cho mỗi điểm cuối webhook.

Truy cập Cấu hình Sự kiện

1

Navigate to Webhook Details

Đi đến Bảng điều khiển Dodo Payments của bạn và chuyển đến Settings > Webhooks.
2

Select Your Endpoint

Nhấp vào endpoint webhook bạn muốn cấu hình.
3

Open Event Settings

Trong trang chi tiết webhook, bạn sẽ thấy phần “Sự kiện đã đăng ký”. Nhấp vào nút Edit để chỉnh sửa đăng ký sự kiện của bạn.

Quản lý Đăng ký Sự kiện

1

View Available Events

Giao diện hiển thị tất cả các sự kiện webhook có sẵn được tổ chức theo cấu trúc phân cấp. Các sự kiện được nhóm theo danh mục (ví dụ: dispute, payment, subscription).
2

Search and Filter

Sử dụng thanh tìm kiếm để nhanh chóng tìm các sự kiện cụ thể bằng cách nhập tên sự kiện hoặc từ khóa.
3

Select Events

Đánh dấu các ô bên cạnh các sự kiện bạn muốn nhận. Bạn có thể:
  • Chọn các sự kiện con riêng lẻ (ví dụ: dispute.accepted, dispute.challenged)
  • Chọn các sự kiện cha để nhận tất cả sự kiện con liên quan
  • Kết hợp và phối hợp các sự kiện cụ thể tùy theo nhu cầu của bạn
4

Review Event Details

Di chuột qua biểu tượng thông tin (ⓘ) bên cạnh mỗi sự kiện để xem mô tả khi nào sự kiện đó được kích hoạt.
5

Save Configuration

Nhấp vào Save để áp dụng các thay đổi hoặc Cancel để hủy bỏ những chỉnh sửa.
Nếu bạn bỏ chọn tất cả sự kiện, endpoint webhook của bạn sẽ không nhận được bất kỳ thông báo nào. Hãy đảm bảo chọn ít nhất các sự kiện mà ứng dụng của bạn cần để hoạt động đúng cách.

Giao hàng Webhook

Thời gian chờ

Webhooks có cửa sổ thời gian chờ 15 giây cho cả kết nối và các hoạt động đọc. Đảm bảo điểm cuối của bạn phản hồi nhanh chóng để tránh thời gian chờ.
Xử lý webhook bất đồng bộ bằng cách xác nhận đã nhận ngay lập tức với mã trạng thái 200, sau đó xử lý phần thực thi trong nền.

Thử lại Tự động

Nếu việc giao hàng webhook thất bại, Dodo Payments sẽ tự động thử lại với độ trễ tăng dần để ngăn ngừa việc làm quá tải hệ thống của bạn.
Cố gắngĐộ trễMô tả
1Ngay lập tứcCố gắng đầu tiên xảy ra ngay lập tức
25 giâyCố gắng thứ hai sau một độ trễ ngắn
35 phútCố gắng thứ ba với độ trễ tăng lên
430 phútCố gắng thứ tư tiếp tục độ trễ
52 giờCố gắng thứ năm với độ trễ kéo dài
65 giờCố gắng thứ sáu với độ trễ lâu hơn
710 giờCố gắng thứ bảy với độ trễ tối đa
810 giờCố gắng cuối cùng - webhook được đánh dấu là thất bại nếu không thành công
Tối đa 8 lần thử lại cho mỗi sự kiện webhook. Ví dụ: nếu một webhook thất bại ba lần trước khi thành công, tổng thời gian gửi là khoảng 35 phút 5 giây kể từ lần thử đầu tiên.
Sử dụng bảng điều khiển Dodo Payments để thử lại thủ công từng thông điệp hoặc khôi phục hàng loạt tất cả các thông điệp thất bại bất cứ lúc nào.

Idempotency

Mỗi sự kiện webhook bao gồm một tiêu đề webhook-id duy nhất. Sử dụng định danh này để thực hiện idempotency và ngăn chặn xử lý trùng lặp.
// 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...
});
Luôn luôn thực hiện các kiểm tra idempotency. Do có các lần thử lại, bạn có thể nhận được cùng một sự kiện nhiều lần.

Thứ tự Sự kiện

Các sự kiện webhook có thể đến không theo thứ tự do các lần thử lại hoặc điều kiện mạng. Thiết kế hệ thống của bạn để xử lý các sự kiện theo bất kỳ trình tự nào.
Bạn sẽ nhận được payload mới nhất tại thời điểm giao hàng, không phụ thuộc vào thời điểm sự kiện webhook ban đầu được phát ra.

Bảo mật Webhooks

Để đảm bảo an toàn cho các webhook của bạn, luôn xác minh các payload và sử dụng HTTPS.

Xác minh Chữ ký

Mỗi yêu cầu webhook bao gồm một tiêu đề webhook-signature, là chữ ký HMAC SHA256 của payload webhook và dấu thời gian, được ký bằng khóa bí mật của bạn.

Xác minh SDK (được khuyến nghị)

Tất cả các SDK chính thức đều bao gồm các trợ giúp tích hợp để xác minh và phân tích các webhook đến một cách an toàn. Có hai phương pháp có sẵn:
  • unwrap(): Xác minh chữ ký bằng khóa bí mật webhook của bạn
  • unsafe_unwrap(): Phân tích payload mà không kiểm tra
Cung cấp khóa bí mật webhook của bạn qua DODO_PAYMENTS_WEBHOOK_KEY khi khởi tạo client 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' });
  }
});

Xác minh Thủ công (thay thế)

Nếu bạn không sử dụng SDK, bạn có thể tự xác minh chữ ký theo thông số kỹ thuật Standard Webhooks:
  1. Xây dựng thông điệp đã ký bằng cách nối webhook-id, webhook-timestamp và chuỗi RAW chính xác của payload, được tách bằng dấu chấm (.).
  2. Tính HMAC SHA256 của chuỗi đó bằng khóa bí mật webhook từ Bảng điều khiển.
  3. So sánh chữ ký đã tính với tiêu đề webhook-signature. Nếu chúng khớp, webhook là xác thực.
Chúng tôi tuân theo đặc tả Standard Webhooks. Bạn có thể sử dụng các thư viện của họ để xác minh chữ ký: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Để biết định dạng payload sự kiện, hãy xem Webhook Payload.

Phản hồi cho Webhooks

  • Bộ xử lý webhook của bạn phải trả về mã trạng thái 2xx status code để xác nhận đã nhận sự kiện.
  • Bất kỳ phản hồi nào khác sẽ được xử lý như một lần thất bại và webhook sẽ được thử lại.

Thực hành tốt nhất

Luôn sử dụng URL HTTPS cho các endpoint webhook. Các endpoint HTTP dễ bị tấn công trung gian và tiết lộ dữ liệu webhook của bạn.
Trả về mã trạng thái 200 ngay khi nhận webhook. Xử lý sự kiện ở chế độ bất đồng bộ để tránh hết thời gian chờ.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Thực hiện idempotency bằng cách sử dụng tiêu đề webhook-id để xử lý cùng một sự kiện nhiều lần mà không gây tác dụng phụ.
Lưu trữ khóa bí mật webhook một cách an toàn bằng cách sử dụng biến môi trường hoặc trình quản lý bí mật. Không bao giờ đẩy bí mật lên hệ thống kiểm soát phiên bản.

Cấu trúc Payload Webhook

Hiểu cấu trúc payload webhook giúp bạn phân tích và xử lý các sự kiện một cách chính xác.

Định dạng Yêu cầu

POST /your-webhook-url
Content-Type: application/json

Tiêu đề

webhook-id
string
bắt buộc
Định danh duy nhất cho sự kiện webhook này. Sử dụng nó để kiểm tra idempotency.
webhook-signature
string
bắt buộc
Chữ ký HMAC SHA256 để xác minh tính xác thực của webhook.
webhook-timestamp
string
bắt buộc
Dấu thời gian Unix (tính bằng giây) khi webhook được gửi.

Thân Yêu cầu

business_id
string
bắt buộc
Định danh doanh nghiệp Dodo Payments của bạn.
type
string
bắt buộc
Loại sự kiện đã kích hoạt webhook này (ví dụ: payment.succeeded, subscription.active).
timestamp
string
bắt buộc
Dấu thời gian định dạng ISO 8601 của thời điểm sự kiện xảy ra.
data
object
bắt buộc
Payload cụ thể theo sự kiện chứa thông tin chi tiết về sự kiện.

Ví dụ 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)
  }
}

Kiểm tra Webhooks

Bạn có thể kiểm tra tích hợp webhook của mình trực tiếp từ bảng điều khiển Dodo Payments để đảm bảo điểm cuối của bạn hoạt động chính xác trước khi đưa vào sử dụng.
Chi tiết Endpoint

Truy cập Giao diện Kiểm tra

1

Navigate to Webhooks

Đi đến Bảng điều khiển Dodo Payments của bạn và chuyển đến Settings > Webhooks.
2

Select Your Endpoint

Nhấp vào endpoint webhook của bạn để truy cập trang chi tiết.
3

Open Testing Tab

Nhấp vào tab Testing để truy cập giao diện kiểm thử webhook.

Kiểm tra Webhook của Bạn

Giao diện kiểm tra cung cấp một cách toàn diện để kiểm tra điểm cuối webhook của bạn:
1

Select Event Type

Sử dụng menu thả xuống để chọn loại sự kiện cụ thể bạn muốn thử (ví dụ: payment.succeeded, payment.failed, v.v.).
Menu thả xuống chứa tất cả các loại sự kiện webhook mà endpoint của bạn có thể nhận.
2

Review Schema and Example

Giao diện hiển thị cả Schema (cấu trúc dữ liệu) và Example (payload mẫu) cho loại sự kiện đã chọn.
3

Send Test Event

Nhấp vào nút Send Example để gửi một webhook kiểm thử đến endpoint của bạn.
Quan trọng: Các thông điệp thất bại được gửi qua giao diện kiểm thử sẽ không được thử lại. Đây chỉ dành cho mục đích kiểm thử.

Xác minh Kiểm tra của Bạn

1

Check Your Endpoint

Giám sát nhật ký endpoint webhook của bạn để xác nhận sự kiện kiểm thử đã được nhận.
2

Verify Signature

Đảm bảo xác minh chữ ký của bạn hoạt động chính xác với payload kiểm thử.
3

Test Response

Xác nhận endpoint của bạn trả về mã trạng thái 2xx để xác nhận đã nhận.

Ví dụ Triển khai

Dưới đây là một triển khai hoàn chỉnh Express.js cho việc xác minh và xử lý 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...
  }
}
Kiểm thử kỹ bộ xử lý webhook của bạn bằng giao diện kiểm thử trên bảng điều khiển trước khi xử lý các sự kiện sản xuất. Việc này giúp phát hiện và sửa lỗi sớm.

Kiểm thử Webhook bằng CLI

Dodo Payments CLI cung cấp hai lệnh để kiểm thử webhook trong quá trình phát triển cục bộ, mà không cần rời khỏi terminal của bạn.

Lắng nghe Webhook trực tiếp trên máy cục bộ

Chuyển tiếp các sự kiện webhook thực từ tài khoản chế độ kiểm thử của bạn đến máy chủ phát triển cục bộ theo thời gian thực:
dodo wh listen
CLI mở một kết nối WebSocket đến Dodo Payments và chuyển tiếp mọi sự kiện webhook đến endpoint cục bộ của bạn (ví dụ: http://localhost:3000/webhook), giữ nguyên tất cả tiêu đề bao gồm cả tiêu đề chữ ký để kiểm tra xác minh.
Bộ lắng nghe chỉ hoạt động với khóa API chế độ kiểm thử. Chạy dodo login và chọn Test Mode trước khi sử dụng lệnh này.

Kích hoạt các sự kiện webhook mô phỏng

Gửi các payload webhook mô phỏng đến bất kỳ endpoint nào mà không cần tạo giao dịch thực tế:
dodo wh trigger
Công cụ tương tác này cho phép bạn chọn từ 22 loại sự kiện được hỗ trợ và gửi các payload mô phỏng thực tế đến endpoint của bạn. Nó lặp lại để bạn có thể kiểm thử nhiều sự kiện trong một phiên.
Các payload webhook mô phỏng từ dodo wh trigger không được ký. Hãy dùng unsafe_unwrap() thay cho unwrap() trong bộ xử lý webhook của bạn chỉ khi đang kiểm thử.

CLI Webhook Testing Docs

Xem tài liệu kiểm thử webhook CLI đầy đủ

Cài đặt nâng cao

Tab Cài đặt nâng cao cung cấp các tùy chọn cấu hình bổ sung để tinh chỉnh hành vi endpoint webhook của bạn.

Giới hạn tốc độ (Throttling)

Kiểm soát tốc độ mà các sự kiện webhook được gửi đến endpoint của bạn để tránh làm quá tải hệ thống.
1

Access Rate Limit Settings

Trong tab Advanced, tìm phần “Rate Limit (throttling)”.
2

Configure Rate Limit

Nhấp vào nút Edit để chỉnh sửa cài đặt giới hạn tốc độ.
Theo mặc định, webhook được áp dụng “Không giới hạn tốc độ”, nghĩa là sự kiện được giao ngay khi chúng xảy ra.
3

Set Limits

Cấu hình giới hạn tốc độ mong muốn của bạn để kiểm soát tần suất giao webhook và tránh quá tải hệ thống.
Sử dụng giới hạn tốc độ khi bộ xử lý webhook của bạn cần thời gian xử lý sự kiện hoặc khi bạn muốn gom nhiều sự kiện lại với nhau.

Header tùy chỉnh

Thêm các header HTTP tùy chỉnh vào tất cả yêu cầu webhook gửi đến endpoint của bạn. Tính năng này hữu ích cho xác thực, định tuyến hoặc thêm siêu dữ liệu vào các yêu cầu webhook.
1

Add Custom Header

Trong phần “Custom Headers”, nhập một KeyValue cho header tùy chỉnh của bạn.
2

Add Multiple Headers

Nhấp vào nút + để thêm các header tùy chỉnh bổ sung khi cần.
3

Save Configuration

Các header tùy chỉnh của bạn sẽ được bao gồm trong tất cả yêu cầu webhook đến endpoint này.

Biến đổi (Transformations)

Biến đổi cho phép bạn chỉnh sửa payload của webhook và chuyển hướng nó đến một URL khác. Tính năng mạnh mẽ này cho phép bạn:
  • Điều chỉnh cấu trúc payload trước khi xử lý
  • Định tuyến webhook đến các endpoint khác nhau tùy theo nội dung
  • Thêm hoặc loại bỏ các trường khỏi payload
  • Biến đổi định dạng dữ liệu
1

Enable Transformations

Bật công tắc Enabled để kích hoạt tính năng biến đổi.
2

Configure Transformation

Nhấp vào Edit transformation để xác định quy tắc biến đổi của bạn.
Bạn có thể sử dụng JavaScript để biến đổi payload webhook và chỉ định một URL đích khác.
3

Test Transformation

Sử dụng giao diện kiểm thử để xác minh biến đổi hoạt động chính xác trước khi đưa vào hoạt động.
Việc biến đổi có thể ảnh hưởng đáng kể đến hiệu suất giao webhook. Hãy kiểm thử kỹ và giữ logic biến đổi đơn giản, hiệu quả.
Biến đổi đặc biệt hữu ích cho:
  • Chuyển đổi giữa các định dạng dữ liệu khác nhau
  • Lọc sự kiện dựa trên tiêu chí cụ thể
  • Thêm các trường tính toán vào payload
  • Định tuyến sự kiện đến các dịch vụ vi mô khác nhau

Giám sát nhật ký Webhook

Tab Logs cung cấp cái nhìn toàn diện về trạng thái giao webhook, giúp bạn giám sát, gỡ lỗi và quản lý các sự kiện webhook hiệu quả.
Nhật ký

Giám sát hoạt động

Tab Activity cung cấp cái nhìn thời gian thực về hiệu suất giao webhook của bạn với phân tích trực quan.
Hoạt động

Cảnh báo qua email

Luôn cập nhật về tình trạng webhook của bạn với các thông báo email tự động. Khi việc giao webhook bắt đầu thất bại hoặc endpoint của bạn không phản hồi, bạn sẽ nhận được cảnh báo qua email để có thể xử lý sự cố nhanh chóng và giữ cho tích hợp hoạt động trơn tru.
Cài đặt cảnh báo Webhook hiển thị cấu hình thông báo email

Bật cảnh báo qua email

1

Navigate to Alerting Settings

Đi đến Bảng điều khiển Dodo Payments của bạn và chuyển đến Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Bật Email notifications để bắt đầu nhận cảnh báo về các vấn đề giao webhook.
3

Configure Email Address

Nhập địa chỉ email nơi bạn muốn nhận các cảnh báo webhook. Chúng tôi sẽ gửi thông báo đến địa chỉ này khi một số sự kiện xảy ra với thiết lập webhook của bạn, chẳng hạn lỗi giao hàng có thể ảnh hưởng đến tích hợp.
Bật cảnh báo qua email để phát hiện sớm các vấn đề giao webhook và duy trì tích hợp tin cậy. Bạn sẽ được thông báo khi giao hàng thất bại hoặc endpoint không phản hồi.

Triển khai lên nền tảng đám mây

Sẵn sàng triển khai bộ xử lý webhook của bạn vào môi trường sản xuất? Chúng tôi cung cấp các hướng dẫn theo từng nền tảng để giúp bạn triển khai webhook lên các nhà cung cấp đám mây phổ biến với các thực hành tốt nhất cho từng nền tảng.
Mỗi hướng dẫn nền tảng bao gồm thiết lập môi trường, xác minh chữ ký và các bước triển khai riêng biệt cho nhà cung cấp đó.