Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
Cổng webhooks của Dodo Payments đã được xây dựng lại với trải nghiệm dashboard nguyên bản. Các endpoint hiện có, signing secret, quy trình xác minh chữ ký, tên sự kiện và webhook payload của bạn không thay đổi. Không cần thực hiện công việc tích hợp nào.
Các mục được đặt ở đâu.
Trong Developer → Webhooks — các tab Endpoints, Event catalog, Logs, Activity và Settings.
Trên từng endpoint — tab Overview, hiển thị thống kê gửi, signing secret và Replay history, cùng các tab Testing và Advanced cũng như các thao tác replay hàng loạt.
Trên một message — mở từ tab Logs, nơi bạn có thể replay từng lần gửi riêng lẻ mà không cần mở endpoint.
1
Access Webhook Settings
Truy cập Dodo Payments Dashboard và đi đến Developer → Webhooks.
2
Create Webhook Endpoint
Nhấp vào Add endpoint để mở side sheet tạo endpoint.
3
Enter Endpoint URL or Choose Integration
Nhập URL nơi bạn muốn nhận webhook events hoặc chọn integration connector để định tuyến events đến dịch vụ bên thứ ba (Slack, Discord, Zapier, Resend, v.v.).
4
Select Events to Receive
Chọn các events cụ thể mà endpoint cần lắng nghe. Events được sắp xếp trong một cây có thể tìm kiếm, được nhóm theo resource. Bạn có thể chọn từng event hoặc một resource cha để nhận tất cả events liên quan.
Chỉ các events được chọn mới kích hoạt webhooks đến endpoint của bạn, giúp tránh lưu lượng và quá trình xử lý không cần thiết.
5
Create Endpoint
Nhấp vào Create endpoint để lưu cấu hình.
6
Get Secret Key
Webhook signing secret của bạn được hiển thị trong tab Overview của endpoint. Bạn sẽ dùng secret này để xác minh tính xác thực của các webhook đã nhận.
Hãy bảo mật webhook secret key và không bao giờ để lộ secret này trong client-side code hoặc public repository.
7
Rotate Secret (Optional)
Khi cần, bạn có thể rotate webhook secret để tăng cường bảo mật. Nhấp vào Rotate secret bên cạnh secret trong tab Overview.
Việc rotate secret sẽ làm secret hiện tại hết hạn và thay thế bằng một secret mới. Secret cũ chỉ còn hợp lệ trong 24 giờ tiếp theo. Sau đó, việc xác minh bằng secret cũ sẽ không thành công.
Hãy rotate secret định kỳ hoặc ngay lập tức nếu bạn nghi ngờ secret hiện tại đã bị xâm phạm.
Thay vì tự xây dựng webhook receiver, bạn có thể định tuyến webhook events trực tiếp đến các dịch vụ bên thứ ba bằng integration connectors. Điều này loại bỏ nhu cầu viết và duy trì các webhook handler tùy chỉnh cho những nền tảng phổ biến.
Một connector thực hiện phép chuyển đổi để biến event của Dodo Payments thành định dạng mà đích đến yêu cầu. Thông tin bạn cung cấp phụ thuộc vào đích đến:
Loại connector
Thông tin bạn cung cấp
Đích đến
Incoming webhook URL
Webhook URL do bạn tạo trong dashboard riêng của nhà cung cấp. Không cần API key.
Bộ chọn connector trong dashboard hiển thị toàn bộ các connector hiện có cho doanh nghiệp của bạn. Vì vậy, hãy xem bảng trên là danh sách các đích đến có hướng dẫn thiết lập từng bước, không phải danh sách đầy đủ. Xem External Integrations để biết mỗi đích đến có thể làm gì sau khi nhận events.
Chọn một connector khi tạo hoặc chỉnh sửa endpoint; side sheet sẽ hiển thị hướng dẫn thiết lập dành cho đích đến đó — chẳng hạn như cách tạo incoming webhook URL trong Slack hoặc vị trí tìm Resend API key. Trước khi lưu, hãy chạy kiểm thử chuyển đổi của connector để xác nhận event được chuyển đổi chính xác cho đích đến.
Sử dụng connector để gửi đến một đích đến được hỗ trợ mà không cần viết code. Nếu cần logic tùy chỉnh, hãy dùng endpoint tiêu chuẩn với transformation thay thế.
Bạn có thể cấu hình các events cụ thể mà mỗi webhook endpoint sẽ nhận.
1
Navigate to Webhook Endpoints
Đi đến Dodo Payments Dashboard và điều hướng đến Developer → Webhooks.
2
Select Your Endpoint
Nhấp vào webhook endpoint bạn muốn cấu hình.
3
Open Event Configuration
Nhấp vào Edit để mở side sheet cấu hình endpoint.
4
Browse Event Types
Bộ chọn event type hiển thị tất cả webhook events hiện có trong một cây có thể tìm kiếm, được nhóm theo resource (ví dụ: payment, subscription, dispute). Sử dụng thanh tìm kiếm để nhanh chóng tìm các events cụ thể theo tên hoặc từ khóa.
5
Select Events
Đánh dấu vào các ô bên cạnh events bạn muốn nhận. Bạn có thể:
Chọn một resource cha để nhận tất cả events liên quan
Kết hợp các events cụ thể tùy theo nhu cầu
6
Save Configuration
Nhấp vào Save để áp dụng thay đổi hoặc Cancel để hủy các sửa đổi.
Nếu bỏ chọn tất cả events, webhook endpoint sẽ không nhận bất kỳ thông báo nào. Hãy đảm bảo chọn ít nhất các events mà ứng dụng của bạn cần để hoạt động chính xác.
Đi đến Developer → Webhooks và mở tab Event catalog. Tab này liệt kê mọi event type mà Dodo Payments có thể gửi, giúp bạn xem những gì hiện có trước khi đăng ký endpoint nhận event. Chọn một event để xem schema và payload mẫu; đây là cách nhanh nhất để kiểm tra cấu trúc của một field bạn dự định đọc.
Webhook Events Guide
Duyệt các events tương tự dưới dạng tài liệu tham khảo, được nhóm theo resource.
Nếu gửi webhook thất bại, Dodo Payments sẽ tự động retry với exponential backoff để tránh làm quá tải hệ thống của bạn.
Lần thử
Độ trễ
Mô tả
1
Ngay lập tức
Lần retry đầu tiên diễn ra ngay
2
5 giây
Lần thử thứ hai sau một khoảng trễ ngắn
3
5 phút
Lần thử thứ ba với backoff tăng lên
4
30 phút
Lần thử thứ tư tiếp tục backoff
5
2 giờ
Lần thử thứ năm với độ trễ kéo dài
6
5 giờ
Lần thử thứ sáu với độ trễ lâu hơn
7
10 giờ
Lần thử thứ bảy với độ trễ tối đa
8
10 giờ
Lần thử 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 retry cho mỗi webhook event. Ví dụ, nếu webhook thất bại ba lần trước khi thành công, tổng thời gian gửi sẽ xấp xỉ 35 phút 5 giây kể từ lần thử đầu tiên.
Sử dụng Dodo Payments dashboard để retry thủ công từng message hoặc khôi phục hàng loạt tất cả message thất bại bất kỳ lúc nào.
Xác minh chữ ký là cách được hỗ trợ để xác thực webhook. Cách này chứng minh rằng request được ký bằng webhook secret của bạn, điều mà kiểm tra ở cấp độ mạng không thể thực hiện.Các lần gửi webhook được thực hiện từ một nhóm địa chỉ IP nguồn thuộc cơ sở hạ tầng gửi của chúng tôi. Nhóm địa chỉ này có thể thay đổi theo thời gian, vì vậy hãy xem các địa chỉ này là chi tiết vận hành thay vì thuộc tính cố định của integration.
Không sử dụng source IP allowlist làm cơ chế xác thực. Allowlist chỉ cho biết request đến từ đâu, không chứng minh request là chính xác hoặc chưa bị sửa đổi — hãy xác minh header webhook-signature trên mọi request, như mô tả trong Xác minh chữ ký.
Nếu infrastructure của bạn nằm sau firewall yêu cầu allowlist rõ ràng, hãy lưu ý những điều sau:
Không hardcode địa chỉ vĩnh viễn. Các range được thêm vào và loại bỏ theo thời gian, rule cũ có thể âm thầm chặn các lần gửi.
Yêu cầu các range hiện tại từ support@dodopayments.com trước khi khóa firewall, để bảo đảm bạn đang sử dụng danh sách mới nhất.
Theo dõi thông báo thay đổi. Khi địa chỉ gửi thay đổi, chúng tôi sẽ thông báo qua email cho các merchant bị ảnh hưởng — hãy áp dụng các cập nhật đó trước ngày được nêu để tránh bỏ lỡ các lần gửi.
Trên các nền tảng serverless và managed hosting, tính năng lọc IP inbound thường không khả dụng hoặc khó duy trì. Xác minh chữ ký là biện pháp kiểm soát phù hợp trong các môi trường này và không yêu cầu allowlist.
Một lần gửi bị chặn được xử lý giống như mọi lỗi khác và được retry theo lịch mô tả trong Automatic Retries. Nếu firewall rule khiến các lần gửi thất bại, bạn có thể gửi lại chúng sau khi sửa rule — xem Phát lại và khôi phục message.
Loại resource. Một trong các giá trị: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt, EntitlementGrant hoặc Payout.
Các field bổ sung thay đổi tùy theo event type. Xem tài liệu riêng của từng event để biết schema đầy đủ.
Kiểm thử kỹ webhook handler bằng giao diện kiểm thử trên dashboard trước khi xử lý event production. Việc này giúp phát hiện và khắc phục sớm các vấn đề.
Forward các webhook event thật từ account test mode đến development server local theo thời gian thực:
dodo wh listen
CLI mở kết nối WebSocket đến Dodo Payments và forward mọi webhook event đến local endpoint (ví dụ: http://localhost:3000/webhook), giữ nguyên tất cả header, bao gồm signature header để kiểm thử xác minh.
Listener chỉ hoạt động với API key test mode. Chạy dodo login và chọn Test Mode trước khi sử dụng command này.
Gửi webhook payload giả lập đến bất kỳ endpoint nào mà không tạo transaction thật:
dodo wh trigger
Công cụ tương tác này cho phép bạn chọn event type và gửi payload giả lập chân thực đến endpoint. Công cụ lặp lại để bạn có thể kiểm thử nhiều event trong cùng một session.Trigger command bao phủ toàn bộ 47 event type mà Dodo Payments gửi, bao gồm các nhóm subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning và entitlement grant — xem Supported Webhook Events để biết danh sách chính xác.
Webhook payload giả lập từ dodo wh trigger không được ký. Chỉ trong quá trình kiểm thử, hãy sử dụng unsafe_unwrap() thay cho unwrap() trong webhook handler.
Tab Logs cung cấp khả năng quan sát toàn diện trạng thái gửi webhook, cho phép bạn giám sát, debug và quản lý webhook event hiệu quả.
1
Navigate to Logs Tab
Đi đến Developer → Webhooks và mở tab Logs.
2
Browse Delivery History
Xem bảng gồm tất cả lần thử gửi webhook với các cột Event type, Message ID, Event ID, Sent at, Attempted at, Response code và Duration.
3
Search and Filter
Sử dụng thanh tìm kiếm để tìm message cụ thể theo ID hoặc event type. Lọc theo status (Succeeded, Failed, Pending, v.v.) để tập trung vào các event cần điều tra.
4
View Message Details
Nhấp vào bất kỳ message nào để mở trang chi tiết message, nơi hiển thị:
Webhook payload đầy đủ
Mọi lần thử gửi cùng response code và duration
Timestamp của từng lần thử
Mọi error message từ endpoint của bạn
Mỗi lần thử có action Replay, cho phép bạn gửi lại riêng message đó mà không cần rời khỏi trang.
Đi đến Developer → Webhooks và mở tab Activity để xem hiệu suất gửi trên các endpoint của bạn.Delivery activity biểu diễn các lần thử theo thời gian, được nhóm thành Attempts per 5 minutes, Attempts per hour hoặc Attempts per day tùy theo khoảng thời gian. Mỗi thanh được chia theo kết quả; khi di chuột lên một phần, bạn sẽ thấy status, số lần thử và tỷ lệ trên tổng số. Trên một endpoint, Delivery stats (last 24h) trong tab Overview tóm tắt cùng thông tin cho ngày vừa qua.
Cột Error rate (24h) trong tab Endpoints cho bạn biết nhanh endpoint nào cần được chú ý trước khi mở chúng.
Sẵn sàng triển khai webhook handler lên production? Chúng tôi cung cấp các guide riêng cho từng platform, giúp bạn triển khai webhook lên các cloud provider phổ biến theo best practice của từng platform.
Vercel
Triển khai webhook lên Vercel bằng serverless function
Cloudflare Workers
Chạy webhook trên edge network của Cloudflare
Supabase Edge Functions
Tích hợp webhook với Supabase
Netlify Functions
Triển khai webhook dưới dạng Netlify serverless function
Mỗi platform guide bao gồm thiết lập environment, xác minh chữ ký và các bước triển khai dành riêng cho provider đó.