
Key Features
Webhooks provide real-time delivery with built-in security, automatic retries, and event filtering. All official SDKs include signature verification helpers, and the dashboard offers testing, monitoring, and replay tools.Getting Started
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
Integration Connectors
Route webhook events directly to third-party services using integration connectors, eliminating the need to build and maintain custom webhook handlers.How Connectors Work
A connector transforms Dodo Payments events into the format the destination expects. Which details you provide depends on the destination:Setting Up a Connector
When creating or editing an endpoint, select a connector and the side sheet shows setup instructions for that destination. Test the transformation before saving to confirm events are converted correctly.Configuring Subscribed Events
Configure which events each webhook endpoint receives.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Check the boxes next to the events you want to receive. You can select individual events, an entire resource, or mix and match.Save Configuration
Event Catalog
Go to Developer → Webhooks and open the Event catalog tab to see every event type Dodo Payments can send. Select an event to view its schema and sample payload.Webhook Events Guide
Webhook Delivery
Timeouts
Webhooks có thời gian chờ 30 giây cho cả thao tác kết nối và đọc. Xử lý webhooks không đồng bộ bằng cách trả về mã trạng thái200 ngay lập tức, sau đó xử lý event ở chế độ nền.
Tự động thử lại
Các lần gửi thất bại sẽ được thử lại với thời gian chờ tăng dần theo cấp số nhân, tối đa 8 lần:Idempotency
Mỗi webhook đều bao gồm headerwebhook-id duy nhất. Lưu ID này để phát hiện và bỏ qua các event trùng lặp, vì các lần thử lại có thể gửi cùng một event nhiều lần.
Thứ tự event
Các event có thể đến không đúng thứ tự do cơ chế thử lại hoặc điều kiện mạng. Mỗi webhook bao gồm một trườngtimestamp; hãy sử dụng trường này để sắp xếp event nếu ứng dụng của bạn yêu cầu. Bạn luôn nhận được trạng thái payload mới nhất tại thời điểm gửi.
Bảo mật Webhooks
Luôn xác thực payload của webhook và sử dụng HTTPS.Xác minh chữ ký
Mỗi webhook bao gồm headerwebhook-signature: chữ ký HMAC SHA256 của payload và timestamp, được ký bằng secret key của bạn.
Xác minh bằng SDK (Khuyến nghị)
Tất cả SDK chính thức đều có các helper tích hợp sẵn. Thiết lậpDODO_PAYMENTS_WEBHOOK_KEY khi khởi tạo client, sau đó gọi unwrap() để xác minh và phân tích payload. Có hai method:
unwrap— Xác minh chữ ký bằng webhook secret key của bạn, sau đó phân tích payload.unsafe_unwrap— Phân tích payload mà không xác minh. Chỉ sử dụng cho mục đích testing.
unwrap / unsafeUnwrap trong TypeScript, unwrap / unsafe_unwrap trong Python và Unwrap / UnsafeUnwrap trong Go.
Xác minh thủ công (Thay thế)
Nếu không sử dụng SDK, hãy tự xác minh chữ ký:- Tạo nội dung đã ký bằng cách nối
webhook-id,webhook-timestampvà request body thô bằng dấu chấm:{id}.{timestamp}.{body}. Sử dụng chính xác body thô như khi nhận được, trước khi phân tích JSON. - Lấy webhook secret của bạn. Nếu secret bắt đầu bằng
whsec_, hãy xóa prefix đó, sau đó base64-decode phần còn lại để lấy signing key. - Tính HMAC-SHA256 của nội dung đã ký bằng signing key, rồi base64-encode kết quả.
- Header
webhook-signaturechứa một hoặc nhiều chữ ký được phân tách bằng dấu cách, mỗi chữ ký có dạngv1,<base64-signature>. Request hợp lệ nếu bất kỳ chữ kýv1nào khớp với chữ ký của bạn. So sánh bằng một hàm constant-time. - Từ chối request nếu
webhook-timestampcách quá xa thời gian hiện tại để ngăn replay attack. Các thư viện Standard Webhooks cho phép sai lệch 5 phút.
Địa chỉ IP nguồn
Xác minh chữ ký là phương thức authentication được hỗ trợ. Phương thức này chứng minh 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 xuất phát từ một pool địa chỉ IP thay đổi theo thời gian. Không dựa vào IP allowlist để authentication. Thay vào đó, luôn xác minh headerwebhook-signature như mô tả trong Xác minh chữ ký.
Nếu firewall của bạn yêu cầu allowlist:
- Không hardcode địa chỉ vĩnh viễn. Các range thay đổi theo thời gian và 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.
- 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ập nhật trước ngày được nêu.
- Luôn bật xác minh chữ ký bất kể bạn thêm rule mạng nào.
Phản hồi Webhooks
Webhook handler của bạn phải trả về2xx status code để xác nhận đã nhận. Mọi response khác đều được xem là thất bại và webhook sẽ được thử lại.
Best Practices
- Chỉ sử dụng HTTPS. HTTP endpoint dễ bị chặn bắt.
- Phản hồi ngay lập tức. Trả về mã trạng thái
200ngay, sau đó xử lý event không đồng bộ. - Triển khai idempotency. Sử dụng header
webhook-idđể phát hiện và bỏ qua event trùng lặp. - Bảo mật secret. Lưu
DODO_PAYMENTS_WEBHOOK_KEYtrong environment variables hoặc secrets manager, không bao giờ lưu trong version control.
Cấu trúc Webhook Payload
Định dạng Request
Headers
Request Body
payment.succeeded, subscription.active).Payload mẫu
Event Types
Event Payloads
Handle Payment Failures
payment.failed và khôi phục các payment bị từ chốiTesting Webhooks
Gửi Event mẫu
Test tích hợp webhook trực tiếp từ dashboard:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Ví dụ triển khai
Triển khai Express.js đầy đủ với xác minh và xử lý webhook:Testing Webhooks với CLI
Dodo Payments CLI có hai command để test webhooks trong quá trình phát triển local.Lắng nghe Webhooks trực tiếp trên Local
Forward các event webhook thực từ account test mode đến development server local của bạn:http://localhost:3000/webhook), đồng thời giữ nguyên toàn bộ header để test xác minh chữ ký.
dodo login và chọn Test Mode trước.Kích hoạt Webhook Event giả lập
Gửi payload webhook giả lập đến bất kỳ endpoint nào mà không tạo transaction thực:subscription.past_due hoặc subscription.unpaused. Xem Supported Webhook Events để biết danh sách chính xác.
CLI Webhook Testing Docs
Cài đặt nâng cao
Tab Advanced cung cấp các tùy chọn cấu hình bổ sung để tinh chỉnh cách endpoint webhook hoạt động.Rate Limiting (Throttling)
Kiểm soát tốc độ gửi webhook event đến endpoint của bạn. Theo mặc định, webhook không bị áp dụng rate limit và event được gửi ngay khi xảy ra.Open Advanced Tab
Configure Rate Limit
Set Your Limit
Custom Headers
Thêm custom HTTP headers vào mọi webhook request được gửi đến endpoint. Hữu ích cho authentication, routing hoặc bổ sung metadata.Add Headers
Add Multiple Headers
Transformations
Transformations cho phép bạn sửa đổi payload của webhook và tùy chọn chuyển hướng payload đến URL khác. Sử dụng transformations để:- Sửa đổi cấu trúc payload trước khi xử lý
- Định tuyến webhook đến các endpoint khác nhau dựa trên nội dung
- Thêm hoặc xóa field khỏi payload
- Chuyển đổi định dạng dữ liệu
Enable Transformations
Configure Transformation
handler().Test Transformation
Theo dõi Webhook Logs
Tab Logs cung cấp thông tin về trạng thái gửi webhook.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- Webhook payload hoàn chỉnh
- 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
Theo dõi Activity
Đi đến Developer → Webhooks và mở tab Activity để xem hiệu suất gửi trên các endpoint. 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 thuộc vào 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.Phát lại và khôi phục Message
Cách gửi lại message phụ thuộc vào số lượng message bạn cần xử lý:- Một message — mở message từ tab Logs và sử dụng action Replay trên lần thử.
- Một khoảng message — mở endpoint, vì các chế độ hàng loạt chỉ tác động đến một endpoint mỗi lần.
Phát lại hàng loạt
Mở endpoint từ Developer → Webhooks. Có ba chế độ, mỗi chế độ chỉ tác động đến endpoint đó:Open More Actions
Set the Range
Start the Run