
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
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.
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.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
Đ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.Quản lý Đăng ký Sự kiện
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).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.
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
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.
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 giao hàng là khoảng 35 phút và 5 giây 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 để triển khai idempotency và ngăn chặn việc 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, 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à timestamp, đượ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 cần xác minh
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-timestamp, và chuỗi thô chính xácpayload, được phân tách bằng dấu chấm (.). - Tính toán HMAC SHA256 của chuỗi đó bằng khóa bí mật webhook của bạn từ Bảng điều khiển.
- 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
Chỉ sử dụng các điểm cuối HTTPS
Chỉ sử dụng các điểm cuối HTTPS
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.
Phản hồi ngay lập tức
Phản hồi ngay lập tức
Trả về mã trạng thái
200 ngay lập tức khi nhận được webhook. Xử lý sự kiện không đồng bộ để tránh thời gian chờ.Xử lý các sự kiện trùng lặp
Xử lý các sự kiện trùng lặp
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ụ.Bảo mật khóa bí mật webhook của bạn
Bảo mật khóa bí mật webhook của bạn
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
Tiêu đề
Đị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.
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.created).Dấu thời gian định dạng ISO 8601 của khi sự kiện xảy ra.
Payload cụ thể cho sự kiện chứa thông tin chi tiết về sự kiện.
Ví dụ Payload
Các Loại Sự kiện
Duyệt tất cả các loại sự kiện webhook có sẵn
Payload Sự kiện
Xem các sơ đồ payload chi tiết cho mỗi 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
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: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 thử nghiệm (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.
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.
Xác minh Kiểm tra của Bạn
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.
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.
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: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.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.
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.Thêm Tiêu đề Tùy chỉnh
Trong phần “Tiêu đề Tùy chỉnh”, nhập một Khóa và Giá trị cho tiêu đề tùy chỉnh của bạn.
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
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.
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ả.
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.
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.
Kích hoạt Cảnh báo qua Email
Đ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.
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.
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.Vercel
Triển khai webhooks lên Vercel với các chức năng serverless
Cloudflare Workers
Chạy webhooks trên mạng biên của Cloudflare
Supabase Edge Functions
Tích hợp webhooks với Supabase
Netlify Functions
Triển khai webhooks dưới dạng các chức năng serverless 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 cụ thể cho nhà cung cấp đó.
