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