Skip to main content
Webhook Cover Image
Webhooks deliver real-time notifications when events occur in your Dodo Payments account. Use them to automate workflows, update your database, send notifications, and keep your systems in sync.
Dodo Payments webhooks follow the Standard Webhooks specification for signature verification and payload structure.

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

1

Go to Developer → Webhooks

In the Dodo Payments Dashboard, navigate to Developer → Webhooks.
2

Click Add Endpoint

Click Add endpoint to create a new webhook receiver.
3

Enter Your Endpoint URL

Provide the HTTPS URL where Dodo Payments will send webhook events, or select an integration connector (Slack, Discord, Zapier, Resend, etc.) to route events to a third-party service without writing code.
4

Select Events

Choose which events to receive. Events are organized by resource (payment, subscription, dispute, etc.). You can select individual events or an entire resource to receive all related events.
5

Save

Click Create endpoint. Your webhook signing secret appears on the endpoint’s Overview tab.
Keep your webhook secret secure. Never expose it in client-side code or version control.
To rotate your webhook secret, open the endpoint and click Rotate secret next to the secret on the Overview tab. The old secret remains valid for 24 hours after rotation.

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: The dashboard shows all connectors available to your business. See External Integrations for what each destination can do with the events.

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.
Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a transformation instead.

Configuring Subscribed Events

Configure which events each webhook endpoint receives.
1

Navigate to Webhook Endpoints

Go to Developer → Webhooks and click on your endpoint.
2

Open Event Configuration

Click Edit to open the endpoint configuration side sheet.
3

Select Events

The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., 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.
4

Save Configuration

Click Save to apply your changes.
If you deselect all events, your webhook endpoint receives every event type. Select only the events your application needs.

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

Browse events as reference documentation, grouped by resource.

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ái 200 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: Sử dụng dashboard để phát lại thủ công các message thất bại hoặc khôi phục hàng loạt các message trong một khoảng thời gian cụ thể.

Idempotency

Mỗi webhook đều bao gồm header webhook-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.
Luôn triển khai các kiểm tra idempotency. Do cơ chế thử lại, bạn có thể nhận 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ường timestamp; 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 header webhook-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ập DODO_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.
Tên method tuân theo quy ước của từng ngôn ngữ: unwrap / unsafeUnwrap trong TypeScript, unwrap / unsafe_unwrap trong Python và Unwrap / UnsafeUnwrap trong Go.
Cung cấp webhook secret thông qua DODO_PAYMENTS_WEBHOOK_KEY khi khởi tạo client Dodo Payments.

Xác minh thủ công (Thay thế)

Nếu không sử dụng SDK, hãy tự xác minh chữ ký:
  1. Tạo nội dung đã ký bằng cách nối webhook-id, webhook-timestamp và 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.
  2. 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.
  3. Tính HMAC-SHA256 của nội dung đã ký bằng signing key, rồi base64-encode kết quả.
  4. Header webhook-signature chứ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ạng v1,<base64-signature>. Request hợp lệ nếu bất kỳ chữ ký v1 nào khớp với chữ ký của bạn. So sánh bằng một hàm constant-time.
  5. Từ chối request nếu webhook-timestamp cá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.
Xem Standard Webhooks libraries để tham khảo các triển khai mẫu. Để xem định dạng event payload, hãy tham khảo Webhook Payload.

Đị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 header webhook-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.
Trên các nền tảng serverless và managed hosting, việc lọc IP inbound thường không khả dụng hoặc không thực tế. 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.
Một lần gửi bị chặn sẽ được xem là thất bại và được thử lại theo lịch mô tả trong Tự động thử lại. Nếu rule firewall khiến các lần gửi thất bại, bạn có thể gửi lại sau khi sửa rule — xem Phát lại và khôi phục message.

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 200 ngay, 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_KEY trong 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

string
bắt buộc
Mã định danh duy nhất của webhook event này. Sử dụng để kiểm tra idempotency.
string
bắt buộc
Chữ ký HMAC SHA256 dùng để xác minh tính xác thực của webhook.
string
bắt buộc
Unix timestamp (tính bằng giây) tại thời điểm webhook được gửi.

Request Body

string
bắt buộc
Business identifier của Dodo Payments.
string
bắt buộc
Loại event đã kích hoạt webhook này (ví dụ: payment.succeeded, subscription.active).
string
bắt buộc
Timestamp được định dạng theo ISO 8601 tại thời điểm event xảy ra.
object
bắt buộc
Payload dành riêng cho từng event, chứa thông tin chi tiết về event này.

Payload mẫu

Event Types

Xem tất cả loại webhook event hiện có

Event Payloads

Xem schema payload chi tiết cho từng event

Handle Payment Failures

Phản hồi payment.failed và khôi phục các payment bị từ chối

Testing Webhooks

Gửi Event mẫu

Test tích hợp webhook trực tiếp từ dashboard:
1

Navigate to Webhooks

Đi đến Developer → Webhooks và nhấp vào endpoint của bạn.
2

Open Testing Tab

Nhấp vào tab Testing.
3

Send Example

Chọn loại event và nhấp Send example. Payload mẫu sẽ được gửi đến endpoint URL của bạn giống hệt một event thực, với cùng cách ký.
4

Check Your Endpoint

Xác nhận event đã đến, việc xác minh chữ ký thành công và bạn đã trả về mã trạng thái 2xx.
Các message thất bại được gửi từ tab Testing sẽ được thử lại theo lịch thông thường, giống mọi webhook khác.

Ví dụ triển khai

Triển khai Express.js đầy đủ với xác minh và xử lý webhook:
Test kỹ webhook handler bằng giao diện testing của dashboard trước khi xử lý event production. Điều này giúp phát hiện và khắc phục vấn đề sớm.

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:
CLI mở một kết nối WebSocket và forward mọi webhook event đến local endpoint (ví dụ: http://localhost:3000/webhook), đồng thời giữ nguyên toàn bộ header để test xác minh chữ ký.
Listener chỉ hoạt động với test mode API keys. Chạy 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:
Công cụ tương tác này cho phép bạn chọn loại event và gửi payload giả lập giống thực tế đến endpoint. Công cụ chạy theo vòng lặp để bạn có thể test nhiều event trong một session. Command trigger bao gồm các nhóm subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning và entitlement grant. Command này không gửi subscription.past_due hoặc subscription.unpaused. Xem Supported Webhook Events để biết danh sách chính xác.
Payload webhook giả lập từ dodo wh trigger không được ký. Chỉ trong quá trình testing, hãy sử dụng method phân tích không xác minh (unsafeUnwrap trong TypeScript, unsafe_unwrap trong Python, UnsafeUnwrap trong Go) trong webhook handler.

CLI Webhook Testing Docs

Xem tài liệu testing webhook đầy đủ cho CLI

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.
1

Open Advanced Tab

Từ trang chi tiết endpoint, nhấp vào tab Advanced.
2

Configure Rate Limit

Mở rộng phần Endpoint throttling.
3

Set Your Limit

Nhập số message tối đa mỗi giây, sau đó nhấp Save. Các lần gửi vượt quá tốc độ này sẽ được xếp hàng thay vì bị loại bỏ.

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.
1

Add Headers

Trong phần Custom headers, nhập tên và giá trị header.
2

Add Multiple Headers

Nhấp Add header cho mỗi header bổ sung, sau đó nhấp Save.

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
1

Enable Transformations

Trong phần Transformation, bật Enable transformation.
2

Configure Transformation

Viết transformation rules bằng JavaScript trong code editor, sau đó nhấp Save. Code phải trả về webhook object từ handler().
3

Test Transformation

Sử dụng transformation test interface để xác minh transformation hoạt động chính xác trước khi go live.
Transformations có thể ảnh hưởng đến hiệu suất gửi webhook. Hãy test kỹ và giữ logic transformation đơn giản, hiệu quả.

Theo dõi Webhook Logs

Tab Logs cung cấp thông tin về trạng thái gửi webhook.
1

Navigate to Logs Tab

Đi đến Developer → Webhooks và mở tab Logs.
2

Browse Delivery History

Xem bảng chứa mọi 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, trang này hiển thị:
  • 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
Mỗi lần thử có action Replay để gửi lại message đó mà không cần rời khỏi trang.

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.
Cột Error rate (24h) trong tab Endpoints cho biết nhanh endpoint nào cần chú ý.

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 đó:
1

Open More Actions

Trên endpoint, mở More actions và chọn một trong ba chế độ trên.
2

Set the Range

Điền khoảng thời gian mà chế độ đó yêu cầu, như liệt kê trong bảng.
3

Start the Run

Nhấp Recover hoặc Replay, tùy theo chế độ bạn đã chọn.
Mỗi lần chạy xuất hiện trong Replay history trên tab Overview của endpoint, cùng với mode, khoảng thời gian, status và số message được gửi lại.

Email Alerts

Dashboard webhooks không cung cấp email alert cho các lần gửi thất bại. Để theo dõi việc gửi, hãy đi đến Developer → Webhooks và kiểm tra tab Logs và Activity.

Triển khai lên Cloud Platforms

Các hướng dẫn dành riêng cho từng platform để triển khai webhook handler lên những cloud provider phổ biến:

Vercel

Triển khai webhooks lên Vercel bằng serverless functions

Cloudflare Workers

Chạy webhooks trên edge network của Cloudflare

Supabase Edge Functions

Tích hợp webhooks với Supabase

Netlify Functions

Triển khai webhooks dưới dạng Netlify serverless functions

Tài liệu API liên quan

Create Webhook

Tạo và cấu hình webhook endpoint bằng lập trình

List Webhooks

Truy xuất và quản lý webhook endpoint của bạn
Lần sửa đổi cuối 28 tháng 9, 2026