Webhook

Webhook là một HTTP endpoint được sử dụng để nhận thông báo sự kiện. Khi một sự kiện cụ thể xảy ra, hệ thống sẽ chủ động gửi một yêu cầu HTTP đến một URL đã được định nghĩa trước (Webhook URL). Webhook thường được dùng để thông báo cho các hệ thống bên ngoài về các thay đổi trạng thái hoặc kết quả của tác vụ bất đồng bộ.

Trường hợp sử dụng phổ biến

Trường hợp sử dụng	Mô tả
Thông báo thanh toán	Nền tảng thanh toán gửi thông báo khi một đơn hàng được thanh toán thành công
Cập nhật xác thực	Dịch vụ đăng nhập bên thứ ba cập nhật trạng thái đăng nhập
Kết quả tác vụ bất đồng bộ	Các tác vụ nền gửi kết quả sau khi hoàn tất
Kích hoạt sự kiện	Hệ thống thông báo cho các dịch vụ bên ngoài khi các sự kiện cụ thể xảy ra

Điểm khác biệt chính so với endpoint thông thường

Mặc dù về mặt kỹ thuật Webhook chỉ là một HTTP endpoint, nhưng nó khác biệt ở cách được sử dụng:

Webhook: Hệ thống khởi tạo lệnh gọi đến URL bên ngoài

Endpoint thông thường: Máy khách gửi yêu cầu đến hệ thống

Tạo một Webhook Endpoint

Trong dự án Apidog của bạn, nhấp vào biểu tượng "+" ở thanh bên trái và chọn "New Other Protocol APIs" → "Webhook".

Sau khi tạo Webhook, hãy điền các trường sau trong trình chỉnh sửa:

Trường	Mô tả
Phương thức yêu cầu	Thường là `POST`
Tên Webhook	Xuất hiện trong tài liệu API và bản xuất OpenAPI (ví dụ: `order`)
Debug URL	Không bắt buộc. URL thực tế được dùng để gửi các yêu cầu kiểm thử (chỉ dùng cho kiểm thử, không được đưa vào tài liệu)
Thông tin khác	Body của yêu cầu, header và các cấu hình khác

Nhấp vào "Save" sau khi bạn đã hoàn tất tất cả các trường bắt buộc.

Gỡ lỗi một Webhook Endpoint

Gỡ lỗi Webhook mô phỏng một lần kích hoạt sự kiện để xác minh liệu dịch vụ bên ngoài có nhận đúng yêu cầu hay không.

Để gỡ lỗi một Webhook:

Nhập Webhook URL của bạn vào trường Debug URL

Nhấp vào "Send" để mô phỏng một lệnh gọi Webhook

Tài liệu Webhook

Tài liệu Webhook bao gồm các chi tiết như tên Webhook, phương thức yêu cầu và body của yêu cầu. Điều này giúp người dùng dễ hiểu hơn về loại dữ liệu sẽ được gửi khi một sự kiện nhất định xảy ra.

Quyền riêng tư của Debug URL

Debug URL sẽ không được đưa vào tài liệu hoặc bản xuất OpenAPI — trường này chỉ dùng cho kiểm thử nội bộ.

Trong tệp OpenAPI được xuất, các Webhook endpoint được liệt kê trong trường webhooks, khác với trường paths của các endpoint thông thường.

Câu hỏi thường gặp

Tại sao cần định nghĩa Webhook riêng trong tài liệu?

Theo đặc tả OpenAPI 3.1:

Các endpoint thông thường được định nghĩa trong trường paths

Các Webhook endpoint được định nghĩa trong trường webhooks

Sự tách biệt rõ ràng này đảm bảo:

Các endpoint thông thường được gọi bởi máy khách bên ngoài để thực hiện hành động hoặc truy xuất dữ liệu

Webhook được hệ thống kích hoạt để thông báo cho các dịch vụ bên ngoài

Trong Apidog, Webhook được xử lý như một loại endpoint riêng biệt nhằm phản ánh chính xác sự khác biệt về hướng này và đảm bảo định dạng phù hợp trong các bản xuất OpenAPI.

Ví dụ:

/orders là một endpoint thông thường được máy khách sử dụng

orderPaid là một Webhook được hệ thống kích hoạt khi một đơn hàng được thanh toán thành công

Webhook có chỉ là một endpoint thông thường không?

Debug URL có hiển thị trong tài liệu API của tôi không?

Trường hợp sử dụng phổ biến#

Điểm khác biệt chính so với endpoint thông thường#

Tạo một Webhook Endpoint#

Gỡ lỗi một Webhook Endpoint#

Tài liệu Webhook#

Câu hỏi thường gặp#

Trường hợp sử dụng phổ biến

Điểm khác biệt chính so với endpoint thông thường

Tạo một Webhook Endpoint

Gỡ lỗi một Webhook Endpoint

Tài liệu Webhook

Câu hỏi thường gặp