Skip to main content
Hình ảnh Bìa Webhook
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.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

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, ActivitySettings.
  • 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 TestingAdvanced 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.

Integration Connectors

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.

Cách Connectors hoạt động

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

Thiết lập Connector

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

Cấu hình Events đã đăng ký

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 từng event (ví dụ: payment.succeeded, payment.failed)
  • 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.

Event Catalog

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

Gửi Webhook

Timeouts

Webhooks có cửa sổ timeout 15 giây cho cả thao tác kết nối và đọc. Hãy đảm bảo endpoint phản hồi nhanh để tránh timeout.
Xử lý webhooks bất đồng bộ bằng cách xác nhận đã nhận ngay lập tức với mã trạng thái 200, sau đó xử lý thực tế ở background.

Automatic Retries

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

Idempotency

Mỗi webhook event chứa header webhook-id duy nhất. Sử dụng identifier này để triển khai idempotency và ngăn xử lý trùng lặp.
Luôn triển khai kiểm tra idempotency. Do cơ chế retry, bạn có thể nhận cùng một event nhiều lần.

Thứ tự Event

Webhook events có thể đến không đúng thứ tự do retry hoặc điều kiện mạng. Hãy thiết kế hệ thống để xử lý events 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 gửi, bất kể webhook event ban đầu được phát ra khi nào.

Bảo mật Webhooks

Để đảm bảo tính bảo mật của webhooks, luôn xác thực payload và sử dụng HTTPS.

Xác minh Chữ ký

Mỗi webhook request bao gồm header webhook-signature, là chữ ký HMAC SHA256 của webhook 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 để xác thực và phân tích incoming webhooks một cách an toàn. Có hai phương thức:
  • unwrap(): Xác minh chữ ký bằng webhook secret key của bạn
  • unsafe_unwrap(): Phân tích payload mà không xác minh
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 (phương án thay thế)

Nếu không sử dụng SDK, bạn có thể tự xác minh chữ ký theo đặc tả Standard Webhooks:
  1. Tạo signed message bằng cách nối webhook-id, webhook-timestamp và chuỗi payload được chuyển thành chuỗi chính xác, ngăn cách bằng dấu chấm (.).
  2. Tính HMAC SHA256 của chuỗi đó bằng webhook secret key từ Dashboard.
  3. So sánh chữ ký đã tính với header webhook-signature. Nếu 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 event payload, xem Webhook Payload.

Địa chỉ IP nguồn

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.
  • Luôn bật xác minh chữ ký bất kể bạn thêm network rule nào.
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.

Phản hồi webhook

  • Webhook handler của bạn phải trả về 2xx status code để xác nhận đã nhận event.
  • Mọi response khác sẽ được xem là lỗi và webhook sẽ được retry.

Best Practices

Luôn sử dụng HTTPS URL cho webhook endpoint. HTTP endpoint dễ bị tấn công man-in-the-middle và làm lộ dữ liệu webhook của bạn.
Trả về status code 200 ngay khi nhận webhook. Xử lý event bất đồng bộ để tránh timeout.
Triển khai idempotency bằng header webhook-id để xử lý an toàn cùng một event nhiều lần mà không gây side effect.
Lưu trữ webhook secret an toàn bằng environment variables hoặc secrets manager. Không bao giờ commit secret vào version control.

Cấu trúc webhook payload

Hiểu cấu trúc webhook payload giúp bạn phân tích cú pháp và xử lý event chính xác.

Đị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 mã này để 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) khi webhook được gửi.

Request body

string
bắt buộc
Mã định danh business của bạn trên 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, cho biết thời điểm event xảy ra.
object
bắt buộc
Payload riêng của event chứa thông tin chi tiết về event.

Payload mẫu

Event Types

Duyệt qua tất cả webhook event type 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

Kiểm thử webhook

Bạn có thể kiểm thử integration webhook trực tiếp từ Dodo Payments dashboard để bảo đảm endpoint hoạt động chính xác trước khi đưa vào production.
1

Navigate to Webhooks

Truy cập Dodo Payments Dashboard và đi đến Developer → Webhooks.
2

Select Your Endpoint

Nhấp vào webhook endpoint để mở trang chi tiết.
3

Open Testing Tab

Nhấp vào tab Testing để mở giao diện kiểm thử webhook.

Gửi event mẫu

Tab Testing gửi một payload mẫu đến endpoint này để bạn xác minh receiver.
1

Select Event Type

Sử dụng Select an event type để chọn event muốn kiểm thử, chẳng hạn payment.succeeded hoặc payment.failed.
2

Send Example

Nhấp Send example. Payload mẫu được gửi đến endpoint URL giống hệt event thật và được ký theo cùng cách.
Message thất bại được gửi từ tab Testing sẽ không được retry. Hãy dùng tính năng này để xác minh receiver, không phải để kiểm thử retry schedule.
3

Check Your Endpoint

Tab ghi lại thời điểm Last example sent được gửi. Xác nhận event đã đến, signature verification thành công và bạn đã trả về status code 2xx.

Ví dụ triển khai

Dưới đây là implementation Express.js hoàn chỉnh minh họa cách xác minh và xử lý webhook:
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 đề.

Kiểm thử webhook bằng CLI

Dodo Payments CLI cung cấp hai command để kiểm thử webhook trong quá trình phát triển local mà không cần rời khỏi terminal.

Lắng nghe webhook trực tiếp trên local

Forward các webhook event thật từ account test mode đến development server local theo thời gian thực:
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.

Kích hoạt webhook event giả lập

Gửi webhook payload giả lập đến bất kỳ endpoint nào mà không tạo transaction thật:
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.

CLI Webhook Testing Docs

Xem tài liệu kiểm thử webhook CLI đầy đủ

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 hành vi của webhook endpoint.

Rate Limiting (Throttling)

Kiểm soát tốc độ gửi webhook event đến endpoint để tránh làm hệ thống quá tải.
1

Open Advanced Tab

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

Configure Rate Limit

Trong phần “Rate Limit (throttling)”, nhấp Edit để sửa cài đặt rate limit.
Theo mặc định, webhook không áp dụng rate limit, nghĩa là event được gửi ngay khi xảy ra.
3

Set Your Limit

Cấu hình rate limit mong muốn để kiểm soát tần suất gửi webhook và ngăn hệ thống quá tải.
Sử dụng rate limiting khi webhook handler cần thời gian xử lý event hoặc khi bạn muốn gộp nhiều event thành một batch.

Custom Headers

Thêm custom HTTP header vào tất cả webhook request được gửi đến endpoint. Tính năng này hữu ích cho authentication, routing hoặc thêm metadata.
1

Add Headers

Trong phần “Custom Headers”, nhập KeyValue cho từng custom header.
2

Add Multiple Headers

Nhấp nút + để thêm các custom header khác khi cần.
Custom header của bạn được bao gồm trong mọi webhook request đến endpoint này.

Transformations

Transformations cho phép bạn sửa payload của webhook và tùy chọn chuyển hướng payload đến URL khác. Tính năng mạnh mẽ này cho phép bạn:
  • Sửa 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

Bật công tắc Enabled để kích hoạt tính năng transformation.
2

Configure Transformation

Nhấp Edit transformation để định nghĩa transformation rule bằng JavaScript.
3

Test Transformation

Sử dụng giao diện kiểm thử transformation để xác minh transformation hoạt động chính xác trước khi đưa vào production.
Transformations có thể ảnh hưởng đến hiệu suất gửi webhook. Hãy kiểm thử kỹ và giữ logic transformation đơn giản, hiệu quả.
Transformations đặc biệt hữu ích cho:
  • Chuyển đổi giữa các định dạng dữ liệu khác nhau
  • Lọc event dựa trên tiêu chí cụ thể
  • Thêm field được tính toán vào payload
  • Định tuyến event đến các microservice khác nhau

Giám sát webhook log

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.

Giám sát activity

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

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ử đó. Không cần mở endpoint.
  • Một phạm vi 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 đó. Phạm vi bạn thiết lập phụ thuộc vào chế độ:
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 phạm vi 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 mode, time range, status và số message được gửi lại.

Email Alerts

Nhận thông báo qua email khi việc gửi webhook đến endpoint thất bại, để bạn có thể xử lý vấn đề trước khi chúng tạo thành backlog.
1

Navigate to Settings Tab

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

Find Email Alerting

Tìm card Email alerting.
3

Configure Email Addresses

Nhập các địa chỉ sẽ nhận alert. Phân tách nhiều địa chỉ bằng dấu phẩy và để trống field để tắt alert.
4

Save

Nhấp Save để áp dụng thay đổi.
Bật email alert để phát hiện sớm vấn đề khi gửi webhook và duy trì integration đáng tin cậy.

Triển khai lên nền tảng cloud

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 đó.

API reference liên quan

Create Webhook

API reference để tạo và cấu hình webhook endpoint theo lập trình

List Webhooks

API reference để truy xuất và quản lý webhook endpoint của bạn
Lần sửa đổi cuối 21 tháng 8, 2026