Chuyển đến nội dung chính
Hì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ộ.
Triển khai webhook của chúng tôi tuân theo thông số kỹ thuật Standard Webhooks, đảm bảo tính tương thích với các thực tiễn tốt nhất trong ngành và các thư viện webhook hiện có.

Tính năng chính

Giao hàng theo thời gian thực

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

Bảo mật theo mặc định

Xác minh chữ ký HMAC SHA256 được bao gồm

Tự động thử lại

Logic thử lại tích hợp với độ trễ tăng dần

Lọc sự kiện

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

Bắt đầu

1

Truy cập Cài đặt Webhook

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

Tạo Điểm cuối Webhook

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

Thêm URL Điểm cuối

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

Chọn Sự kiện để Nhận

Chọn các sự kiện cụ thể mà điểm cuối 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 đã chọn mới kích hoạt webhooks đến điểm cuối của bạn, giúp bạn tránh lưu lượng không cần thiết và xử lý.
5

Lấy Khóa Bí mật

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

Xoay Khóa Bí mật (Tùy chọn)

Nếu cần, bạn có thể xoay khóa bí mật webhook của mình để tăng cường bảo mật. Nhấp vào nút Xoay Khóa trong cài đặt webhook của bạn.
Việc xoay khóa bí mật sẽ làm hết hạnthay thế nó bằng một cái mới. Khóa cũ chỉ có giá trị trong 24 giờ tiếp theo. Sau đó, việc cố gắng xác minh bằng khóa cũ sẽ thất bại.
Sử dụng việc xoay khóa bí mật định kỳ hoặc ngay lập tức nếu bạn nghi ngờ rằng khóa hiện tại của bạn đã 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

Đi đến Chi tiết Webhook

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

Chọn Điểm cuối của Bạn

Nhấp vào điểm cuối webhook mà bạn muốn cấu hình.
3

Mở Cài đặt Sự kiện

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

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

1

Xem Các Sự kiện Có sẵn

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

Tìm kiếm và Lọc

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

Chọn Sự kiện

Đá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ả các sự kiện con liên quan
  • Kết hợp và chọn các sự kiện cụ thể dựa trên nhu cầu của bạn
4

Xem Chi tiết Sự kiện

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

Lưu Cấu hình

Nhấp vào Lưu để áp dụng các thay đổi của bạn, hoặc Hủy để bỏ qua các sửa đổi.
Nếu bạn bỏ chọn tất cả các sự kiện, điểm cuối webhook của bạn sẽ không nhận được bất kỳ thông báo nào. Hãy chắc chắn 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ý webhooks một cách bất đồng bộ bằng cách xác nhận việc nhận ngay lập tức với mã trạng thái 200, sau đó xử lý thực tế 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 giao hàng là khoảng 35 phút và 5 giây từ lần thử đầu tiên.
Sử dụng bảng điều khiển Dodo Payments để thử lại thủ công các tin nhắn riêng lẻ hoặc khôi phục hàng loạt tất cả các tin nhắn đã 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 để triển khai idempotency và ngăn ngừa việc 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 triển khai các kiểm tra idempotency. Do 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, bất kể khi nào sự kiện webhook được phát ra ban đầu.

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, một 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 cách sử dụng khóa bí mật webhook của bạn
  • unsafe_unwrap(): Phân tích các payload mà không cần xác minh
Cung cấp khóa bí mật webhook của bạn qua DODO_PAYMENTS_WEBHOOK_KEY khi khởi tạo khách hàng 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 thô chính xác payload, được phân tách bằng các dấu chấm (.).
  2. Tính toán HMAC SHA256 của chuỗi đó bằng cách sử dụng khóa bí mật webhook của bạn từ Bảng điều khiển.
  3. So sánh chữ ký đã tính toán 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 thông số kỹ thuậ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, xem Webhook Payload.

Phản hồi cho Webhooks

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

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

Luôn sử dụng các URL HTTPS cho các điểm cuối webhook. Các điểm cuối HTTP dễ bị tấn công man-in-the-middle và làm lộ dữ liệu webhook của bạn.
Trả về mã trạng thái 200 ngay lập tức khi nhận được webhook. Xử lý sự kiện một cách bất đồng bộ để tránh 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);
});
Triển khai idempotency bằng cách sử dụng tiêu đề webhook-id để xử lý an toàn cùng một sự kiện nhiều lần mà không có tác dụng phụ.
Lưu trữ khóa bí mật webhook của bạn một cách an toàn bằng cách sử dụng các biến môi trường hoặc trình quản lý bí mật. Không bao giờ cam kết bí mật vào 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
required
Định danh duy nhất cho sự kiện webhook này. Sử dụng điều này cho các kiểm tra idempotency.
webhook-signature
string
required
Chữ ký HMAC SHA256 để xác minh tính xác thực của webhook.
webhook-timestamp
string
required
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
required
Định danh doanh nghiệp Dodo Payments của bạn.
type
string
required
Loại sự kiện đã kích hoạt webhook này (ví dụ: payment.succeeded, subscription.created).
timestamp
string
required
Dấu thời gian định dạng ISO 8601 của khi sự kiện xảy ra.
data
object
required
Payload cụ thể cho 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 Điểm cuối

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

1

Đi đến Webhooks

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

Chọn Điểm cuối của Bạn

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

Mở Tab Kiểm tra

Nhấp vào tab Kiểm tra để truy cập giao diện kiểm tra 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

Chọn Loại Sự kiện

Sử dụng menu thả xuống để chọn loại sự kiện cụ thể mà bạn muốn kiểm tra (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 có sẵn mà điểm cuối của bạn có thể nhận được.
2

Xem Sơ đồ và Ví dụ

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

Gửi Sự kiện Kiểm tra

Nhấp vào nút Gửi Ví dụ để gửi một webhook thử nghiệm đến điểm cuối của bạn.
Quan trọng: Các tin nhắn thất bại được gửi qua giao diện kiểm tra sẽ không được thử lại. Điều này chỉ dành cho mục đích kiểm tra.

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

1

Kiểm tra Điểm cuối của Bạn

Theo dõi nhật ký điểm cuối webhook của bạn để xác nhận rằng sự kiện kiểm tra đã được nhận.
2

Xác minh Chữ ký

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

Kiểm tra Phản hồi

Xác nhận rằng điểm cuối của bạn trả về mã trạng thái 2xx để xác nhận việc 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.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
Kiểm tra kỹ lưỡng bộ xử lý webhook của bạn bằng cách sử dụng giao diện kiểm tra bảng điều khiển trước khi xử lý các sự kiện sản xuất. Điều này giúp xác định và sửa chữa các vấn đề sớm.

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 điểm cuối 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 giao đến điểm cuối của bạn để ngăn ngừa việc làm quá tải hệ thống của bạn.
1

Truy cập Cài đặt Giới hạn Tốc độ

Trong tab Nâng cao, tìm phần “Giới hạn Tốc độ (throttling)”.
2

Cấu hình Giới hạn Tốc độ

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

Đặt Giới hạn

Cấu hình giới hạn tốc độ mà bạn mong muốn để kiểm soát tần suất giao hàng webhook và ngăn ngừa 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ý các sự kiện hoặc khi bạn muốn nhóm nhiều sự kiện lại với nhau.

Tiêu đề Tùy chỉnh

Thêm các tiêu đề HTTP tùy chỉnh vào tất cả các yêu cầu webhook gửi đến điểm cuối của bạn. Điều 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 của bạn.
1

Thêm Tiêu đề Tùy chỉnh

Trong phần “Tiêu đề Tùy chỉnh”, nhập một KhóaGiá trị cho tiêu đề tùy chỉnh của bạn.
2

Thêm Nhiều Tiêu đề

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

Lưu Cấu hình

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

Biến đổi

Biến đổi cho phép bạn sửa đổi payload của một 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:
  • Sửa đổi cấu trúc payload trước khi xử lý
  • Định tuyến các webhook đến các điểm cuối khác nhau dựa trên nội dung
  • Thêm hoặc xóa các trường từ payload
  • Chuyển đổi định dạng dữ liệu
1

Kích hoạt Biến đổi

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

Cấu hình Biến đổi

Nhấp vào Chỉnh sửa biến đổi để xác định các 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 mục tiêu khác.
3

Kiểm tra Biến đổi

Sử dụng giao diện kiểm tra để xác minh rằng biến đổi của bạn hoạt động chính xác trước khi đưa vào sử dụng.
Biến đổi có thể ảnh hưởng đáng kể đến hiệu suất giao hàng webhook. Kiểm tra kỹ lưỡng và giữ cho logic biến đổi đơn giản và 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 các sự kiện dựa trên các tiêu chí cụ thể
  • Thêm các trường tính toán vào payload
  • Định tuyến các sự kiện đến các microservices khác nhau

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

Tab Nhật ký cung cấp cái nhìn toàn diện về trạng thái giao hàng webhook của bạn, cho phép bạn theo dõi, gỡ lỗi và quản lý các sự kiện webhook một cách hiệu quả.
Nhật ký

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

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

Cảnh báo qua Email

Giữ thông tin 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 hàng webhook bắt đầu thất bại hoặc điểm cuối của bạn ngừng phản hồi, bạn sẽ nhận được cảnh báo qua email để nhanh chóng giải quyết các vấn đề và giữ cho các tích hợp của bạn 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 qua email

Kích hoạt Cảnh báo qua Email

1

Đi đến Cài đặt Cảnh báo

Đi đến Bảng điều khiển Dodo Payments của bạn và điều hướng đến Bảng điều khiển → Webhooks → Cảnh báo.
2

Kích hoạt Thông báo qua Email

Bật Thông báo qua Email để bắt đầu nhận cảnh báo về các vấn đề giao hàng webhook.
3

Cấu hình Địa chỉ Email

Nhập địa chỉ email nơi bạn muốn nhận 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 cài đặt webhook của bạn, chẳng hạn như các vấn đề giao hàng có thể ảnh hưởng đến các tích hợp của bạn.
Kích hoạt cảnh báo qua email để phát hiện sớm các vấn đề giao hàng webhook và duy trì các tích hợp đáng tin cậy. Bạn sẽ được thông báo khi các giao hàng thất bại hoặc điểm cuối của bạn trở nên không phản hồi.

Triển khai lên Các Nền tảng Đám mây

Sẵn sàng triển khai bộ xử lý webhook của bạn vào sản xuất? Chúng tôi cung cấp các hướng dẫn cụ thể cho từng nền tảng để giúp bạn triển khai webhooks đến các nhà cung cấp đám mây phổ biến với các thực tiễn tốt nhất cho mỗi 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 cụ thể cho nhà cung cấp đó.