Chuyển đến nội dung chính

GitHub Repository

Hướng dẫn cài đặt và mã nguồn đầy đủ

Thiết lập nhanh

1. Yêu cầu trước khi bắt đầu

2. Cài đặt các phụ thuộc

3. Thiết lập cơ sở dữ liệu

  1. Đăng ký Neon
  2. Tạo dự án mới
  3. Mở Trình soạn thảo SQL
  4. Sao chép và dán nội dung của schema.sql
  5. Chạy truy vấn
  6. Lấy chuỗi kết nối từ Neon → Chi tiết kết nối

4. Thiết lập các biến môi trường ban đầu

Thông qua Vercel CLI:
Lưu ý: Chúng tôi sẽ thiết lập DODO_PAYMENTS_WEBHOOK_KEY sau khi triển khai khi bạn đã có URL webhook.

5. Triển khai

6. Lấy URL Webhook của bạn

URL webhook của bạn là:

7. Đăng ký Webhook trong Bảng điều khiển DodoPayments

  1. Truy cập Bảng điều khiển DodoPayments → Nhà phát triển → Webhooks
  2. Tạo đầu cuối webhook mới
  3. Cấu hình URL webhook của bạn làm đầu cuối
  4. Kích hoạt các sự kiện đăng ký sau:
    • subscription.active
    • subscription.cancelled
    • subscription.renewed
  5. Sao chép Signing Secret

8. Thiết lập Khóa Webhook & Triển khai lại

Chức năng của nó

Xử lý các sự kiện đăng ký và lưu trữ chúng trong PostgreSQL:
  • subscription.active - Tạo/cập nhật hồ sơ khách hàng và đăng ký
  • subscription.cancelled - Đánh dấu đăng ký là đã hủy
  • subscription.renewed - Cập nhật ngày thanh toán tiếp theo

Tính năng chính

Xác minh chữ ký - Sử dụng thư viện dodopayments
Idempotency - Ngăn chặn xử lý trùng lặp bằng ID webhook
Ghi nhận sự kiện - Hành trình kiểm toán hoàn chỉnh trong bảng webhook_events
Xử lý lỗi - Được ghi lại và có thể thử lại
Lưu ý: Cài đặt này trình bày cách xử lý ba sự kiện đăng ký cốt lõi (subscription.active, subscription.cancelled, subscription.renewed) với các trường tối thiểu. Bạn có thể dễ dàng mở rộng để hỗ trợ thêm các loại sự kiện và trường dựa trên nhu cầu.

Tệp cấu hình

Sơ đồ cơ sở dữ liệu

Các bảng được tạo:
  • customers - Email, tên, dodo_customer_id
  • subscriptions - Trạng thái, số tiền, next_billing_date, liên kết với khách hàng
  • webhook_events - Nhật ký sự kiện với webhook_id để đảm bảo idempotency

Mã triển khai

Cách hoạt động

Bộ xử lý webhook:
  1. Tắt phân tích thân - Để truy cập thân thô cho việc xác minh chữ ký
  2. Xác minh chữ ký - Đảm bảo yêu cầu đến từ DodoPayments bằng HMAC-SHA256
  3. Kiểm tra trùng lặp - Dùng ID webhook để ngăn xử lý cùng sự kiện hai lần
  4. Ghi nhận sự kiện - Lưu webhook thô trong bảng webhook_events cho hành trình kiểm toán
  5. Xử lý sự kiện - Tạo hoặc cập nhật khách hàng và đăng ký trong Neon
  6. Xử lý lỗi - Ghi lại lỗi và đánh dấu sự kiện chưa xử lý để thử lại

Kiểm tra

Phát triển cục bộ:
Xem nhật ký trong Bảng điều khiển Vercel:
  1. Chọn dự án của bạn
  2. Đi tới Triển khai → triển khai mới nhất
  3. Nhấp vào Chức năngNhật ký
Cấu hình trong Bảng điều khiển DodoPayments:
  1. Truy cập Nhà phát triển → Webhooks
  2. Thêm điểm cuối với URL Chức năng Vercel của bạn
  3. Kích hoạt: subscription.active, subscription.cancelled, subscription.renewed

Các vấn đề thường gặp

Tài nguyên

Lần sửa đổi cuối 22 tháng 5, 2026