
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
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.
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.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
Navigate to Webhook Details
Đi đến Bảng điều khiển Dodo Payments của bạn và chuyển đến
Settings > Webhooks.Quản lý Đăng ký Sự kiện
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).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.
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
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.
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ờ.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ả |
|---|---|---|
| 1 | Ngay lập tức | Cố gắng đầu tiên xảy ra ngay lập tức |
| 2 | 5 giây | Cố gắng thứ hai sau một độ trễ ngắn |
| 3 | 5 phút | Cố gắng thứ ba với độ trễ tăng lên |
| 4 | 30 phút | Cố gắng thứ tư tiếp tục độ trễ |
| 5 | 2 giờ | Cố gắng thứ năm với độ trễ kéo dài |
| 6 | 5 giờ | Cố gắng thứ sáu với độ trễ lâu hơn |
| 7 | 10 giờ | Cố gắng thứ bảy với độ trễ tối đa |
| 8 | 10 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.
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.
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ạnunsafe_unwrap(): Phân tích payload mà không kiểm tra
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:- Xây dựng thông điệp đã ký bằng cách nối
webhook-id,webhook-timestampvà chuỗi RAW chính xác củapayload, được tách bằng dấu chấm (.). - Tính HMAC SHA256 của chuỗi đó bằng khóa bí mật webhook từ Bảng điều khiển.
- 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
Use HTTPS endpoints only
Use HTTPS endpoints only
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.
Respond immediately
Respond immediately
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ờ.Handle duplicate events
Handle duplicate events
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ụ.Secure your webhook secret
Secure your webhook secret
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
Tiêu đề
Định danh duy nhất cho sự kiện webhook này. Sử dụng nó để kiểm tra idempotency.
Chữ ký HMAC SHA256 để xác minh tính xác thực của webhook.
Dấu thời gian Unix (tính bằng giây) khi webhook được gửi.
Thân Yêu cầu
Định danh doanh nghiệp Dodo Payments của bạn.
Loại sự kiện đã kích hoạt webhook này (ví dụ:
payment.succeeded, subscription.active).Dấu thời gian định dạng ISO 8601 của thời điểm sự kiện xảy ra.
Payload cụ thể theo sự kiện chứa thông tin chi tiết về sự kiện.
Ví dụ Payload
Event Types
Duyệt tất cả các loại sự kiện webhook có sẵn
Event Payloads
Xem sơ đồ payload chi tiết cho từng sự kiện
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.
Truy cập Giao diện Kiểm tra
Navigate to Webhooks
Đi đến Bảng điều khiển Dodo Payments của bạn và chuyển đến
Settings > Webhooks.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: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.
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.
Xác minh Kiểm tra của Bạn
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.
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: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: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ế: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.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.
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.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
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.
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ả.
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.
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.
Bật cảnh báo qua email
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.
Enable Email Notifications
Bật Email notifications để bắt đầu nhận cảnh báo về các vấn đề giao webhook.
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.Vercel
Triển khai webhook lên Vercel với các hàm không máy chủ
Cloudflare Workers
Chạy webhook trên mạng lưới biên Cloudflare
Supabase Edge Functions
Tích hợp webhook với Supabase
Netlify Functions
Triển khai webhook như các hàm không máy chủ của Netlify
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 đó.
