Webhook là gì? Sự kiện, Giao hàng, Bảo mật, và Thiết kế

API Scraping không cần scrap có thể gửi yêu cầu HTTP POST tới một URL webhook đã cấu hình khi một tác vụ scraping không đồng bộ hoàn tất.

Webhook là gì?

Một webhook là một cơ chế thông qua đó một hệ thống gửi yêu cầu HTTP đến một hệ thống khác sau khi xảy ra một sự kiện. Ứng dụng nhận được đăng ký một URL điểm cuối và thường chọn các loại sự kiện như nhiệm vụ hoàn thành, hóa đơn đã thanh toán, bản ghi đã cập nhật, triển khai đã hoàn thành hoặc tin nhắn đã được gửi. Khi sự kiện xảy ra, nhà sản xuất gọi điểm cuối đó với dữ liệu sự kiện và siêu dữ liệu.

Một webhook đôi khi được mô tả là một cuộc gọi API ngược. Trong một tương tác API thông thường, người tiêu dùng khởi xướng một yêu cầu để đọc hoặc thay đổi trạng thái. Với một webhook, nhà sản xuất khởi xướng một yêu cầu để thông báo cho người tiêu dùng. URL nhận vẫn là một điểm cuối HTTP, và việc triển khai phải áp dụng các thực tiễn bảo mật API thông thường, xác thực, tính khả dụng và quan sát.

I'm sorry, but it seems that you haven't provided any text for translation. Please provide the text you'd like me to translate, and I'll be happy to assist! Tiêu chuẩn về Webhooks thu thập các quy ước cho việc gửi webhook an toàn và tương tác. Nó bao gồm payloads, metadata sự kiện, chữ ký, và hành vi vận hành, trong khi các nhà cung cấp riêng lẻ vẫn xác định các loại sự kiện và hợp đồng của riêng họ.

Cách một Webhook hoạt động

1. Người tiêu dùng đăng ký một điểm cuối. Đăng ký có thể xảy ra trong bảng điều khiển hoặc API và thường liên kết một bí mật với đăng ký.
2. Người tiêu dùng chọn sự kiện. Các gói đăng ký hẹp giảm thiểu lưu lượng truy cập và việc lộ dữ liệu không cần thiết.
3. Nhà sản xuất ghi lại một sự kiện. Một hành động miền tạo ra một sự kiện không thể thay đổi hoặc nhiệm vụ giao hàng với một định danh ổn định.
4. Nhà sản xuất xây dựng payload. Nó tuần tự hóa một loại sự kiện, ID sự kiện, thời gian xảy ra, phiên bản sơ đồ và dữ liệu liên quan.
5. Người sản xuất ký vào biên nhận giao hàng. Chữ ký bao phủ thân thể thô và siêu dữ liệu độ tươi theo sơ đồ được ghi chép.
6. Nhà sản xuất gửi một yêu cầu HTTP. POST với thân JSON là phổ biến, nhưng hợp đồng xác định phương thức và loại phương tiện.
7. Người tiêu dùng xác nhận và ghi lại điều đó. Điểm kết nối kiểm tra phương tiện vận chuyển, chữ ký, dấu thời gian, ID sự kiện, sơ đồ và đăng ký trước khi chấp nhận sự kiện.
8. Người tiêu dùng thừa nhận. Nó trả lại trạng thái thành công đã được ghi chép sau khi chấp nhận bền bỉ và thực hiện xử lý lâu hơn thông qua một hàng đợi hoặc công nhân.

Ví dụ về Payload Webhook

Một phong bì sự kiện nhỏ có thể tách siêu dữ liệu khỏi dữ liệu miền:

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

Ngày được hiển thị là một hằng số mã minh họa chứ không phải là dấu ấn xuất bản. ID sự kiện hỗ trợ việc loại bỏ trùng lặp, loại chọn bộ xử lý và lược đồ, thời gian xảy ra mô tả sự kiện miền, và phiên bản điều khiển sự phát triển của payload. Thời gian giao hàng thuộc về metadata yêu cầu khi lược đồ chữ ký sử dụng nó.

Đừng giả định rằng thân webhook chứa toàn bộ tài nguyên hiện tại. Một số nhà sản xuất gửi thông báo mỏng với một ID, sau đó người tiêu dùng gọi API để lấy trạng thái hiện tại được ủy quyền. Những người khác gửi một bức tranh sự kiện hoàn chỉnh. Hợp đồng nên nêu rõ liệu tải trọng đại diện cho sự kiện, tài nguyên sau sự kiện, hay một con trỏ.

Webhooks so với Polling, APIs, và WebSockets

Các hệ thống quan trọng thường kết hợp các mẫu. Một webhook cung cấp thông báo nhanh chóng, trong khi một quy trình đối chiếu theo lịch trình so sánh trạng thái API hiện tại với trạng thái cục bộ. Webhook cải thiện độ trễ; việc đối chiếu phát hiện các khoảng trống hoặc thay đổi chính sách mà không giả định rằng một con đường giao hàng là hoàn hảo.

Cách thức hoạt động của Chữ ký Webhook

Một thiết kế bí mật chia sẻ thường sử dụng một hàm băm có khóa trên thân yêu cầu thô chính xác cộng với siêu dữ liệu như dấu thời gian giao hàng và ID sự kiện. HMAC là một cấu trúc tiêu chuẩn cho xác thực thông điệp, được định nghĩa trong RFC 2104Các nhà cung cấp khác sử dụng chữ ký không đối xứng để người tiêu dùng có thể xác minh bằng một khóa công khai.

Người tiêu dùng phải tuân theo thuật toán byte-for-byte của nhà cung cấp. Phân tích tiêu đề chữ ký theo định dạng phiên bản của nó, tái tạo nội dung đã ký chính xác, tính toán giá trị mong đợi, và so sánh thông qua một hàm thời gian không đổi. Chỉ sau khi xác minh, mã mới nên phân tích và tin tưởng vào tải trọng JSON.

Middleware khung có thể làm gián đoạn việc xác minh khi nó phân tích JSON và tuần tự hóa nó lại. Khoảng trắng, thứ tự thuộc tính, thoát ký tự, và định dạng số có thể thay đổi mặc dù dữ liệu có vẻ tương đương. Nắm bắt các byte thân nguyên thủy trước khi phân tích thân thông thường, sau đó chuyển các byte đã xác minh cho trình phân tích JSON.

Bảo vệ chống phát lại và Tính idempotent

Một webhook cũ hợp lệ có thể bị phát lại một cách độc hại nếu chữ ký không bao giờ hết hạn. Do đó, các sơ đồ chữ ký bao gồm một dấu thời gian giao hàng hoặc một giá trị tươi mới khác. Người nhận chỉ chấp nhận một khoảng thời gian nhỏ đã được tài liệu hóa và nên giữ đồng hồ của mình được đồng bộ hóa. Kiểm tra dấu thời gian bổ sung, chứ không thay thế, việc loại trừ ID sự kiện.

Idempotency có nghĩa là xử lý cùng một sự kiện logic nhiều hơn một lần sẽ cho ra kết quả kinh doanh giống như xử lý nó một lần. Lưu ID sự kiện ổn định của nhà sản xuất trong một bảng với ràng buộc duy nhất, lý tưởng là trong cùng một giao dịch áp dụng thay đổi kinh doanh. Đánh dấu một sự kiện là "đã thấy" trước khi cập nhật kinh doanh có thể làm mất công việc nếu quá trình dừng lại giữa các hành động đó.

Một số thao tác tự nhiên là idempotent, chẳng hạn như đặt trạng thái của một bản ghi thành một phiên bản cụ thể. Những thao tác khác, chẳng hạn như tăng số dư hoặc gửi tin nhắn, cần một bản ghi idempotency gắn với ID sự kiện. Loại bỏ trùng lặp bằng cách sử dụng định danh đã được tài liệu hóa của nhà sản xuất, không phải bằng cách băm dữ liệu tải, vì hai sự kiện hợp lệ có thể có nội dung giống hệt nhau.

Sắp xếp và Phiên bản Sự kiện

Đơn hàng giao hàng có thể khác với thứ tự xảy ra vì các sự kiện có thể di chuyển qua các công nhân, khu vực hoặc hàng đợi riêng biệt. Một bản cập nhật mới hơn có thể đến trước một bản cũ hơn. Người tiêu dùng không nên coi thứ tự đến như thứ tự kinh doanh trừ khi nhà sản xuất đảm bảo rõ ràng điều đó cho việc đăng ký.

Bao gồm một phiên bản tài nguyên, chuỗi, hoặc thời gian xảy ra sự kiện với ngữ nghĩa được xác định. Chỉ áp dụng bản cập nhật trạng thái khi phiên bản của nó mới hơn phiên bản địa phương. Đối với các sự kiện đại diện cho các hành động không thể thay đổi thay vì các bức ảnh trạng thái, hãy giữ nguyên các quy tắc chuỗi sự kiện đã được thiết lập bởi miền.

Phiên bản lược đồ tách biệt với phiên bản tài nguyên. Phiên bản lược đồ mô tả hình dạng tải trọng; phiên bản tài nguyên mô tả trạng thái của một thực thể cụ thể. Giữ cho các khái niệm tách biệt ngăn chặn việc thay đổi định dạng tải trọng xuất hiện như một bản ghi doanh nghiệp mới hơn.

Xác nhận đầu tiên, Xử lý qua hàng đợi

Một điểm cuối webhook nên thực hiện công việc có giới hạn: ép buộc kích thước yêu cầu, xác minh chữ ký, xác thực phong bì, đăng ký ID sự kiện, lưu trữ hoặc xếp hàng sự kiện đã chấp nhận, và trả về phản hồi thành công đã được tài liệu hóa. Các phép nối cơ sở dữ liệu chậm, gọi API bên ngoài, tạo tệp và gửi email thuộc về các công nhân.

Chấp nhận bền vững là điều quan trọng. Việc trả về thành công trước khi sự kiện được ghi lại có thể làm mất nó nếu quy trình dừng lại. Chờ đợi mọi hành động hạ nguồn trước khi phản hồi khiến nhà sản xuất giữ một kết nối và có thể gây ra việc giao hàng lặp đi lặp lại khi điểm kết thúc vượt quá thời gian phản hồi của nó.

Tin nhắn hàng đợi nên chứa sự kiện đã được xác thực, ngữ cảnh đăng ký và các định danh theo dõi an toàn. Các bí mật được sử dụng để xác thực chữ ký không thuộc về tải trọng hàng đợi.

Bảo mật Đăng ký Điểm cuối

Nếu người dùng có thể đăng ký các URL webhook tùy ý, nhà sản xuất trở thành một khách hàng HTTP hành động dựa trên đầu vào của người dùng. Hệ thống phải bảo vệ chống lại việc giả mạo yêu cầu phía máy chủ. Bảng Cheat Sheet Ngăn Chặn SSRF của OWASP mô tả danh sách cho phép và các điều khiển tầng mạng.

Yêu cầu HTTPS cho các điểm cuối công cộng, giải quyết và xác thực các đích đến, chặn loopback, link-local, riêng tư, metadata và các phạm vi dịch vụ nội bộ, và áp dụng lại các kiểm tra sau khi chuyển hướng và phân giải DNS theo chính sách đã chọn. Giới hạn cổng, phương thức, byte phản hồi, thời gian kết nối và hành vi chuyển hướng.

Xác minh quyền sở hữu điểm cuối trong quá trình đăng ký thông qua một thử thách hoặc bàn tay ký. Xem xét các thân phản hồi webhook là không đáng tin cậy và không tiết lộ chi tiết mạng nội bộ thông qua các thông điệp lỗi giao hàng.

Các Trường Hợp Sử Dụng Webhook Thông Dụng

Khả năng quan sát và Hoạt động

Theo dõi ID sự kiện, ID đăng ký, loại sự kiện, phiên bản sơ đồ, thời gian nhận, quyết định xác minh, trạng thái công nhận, trạng thái xử lý, và các nhận dạng tương quan an toàn. Không ghi lại bí mật ký, tiêu đề ủy quyền đầy đủ hoặc các trường tải trọng nhạy cảm.

Đo lường độ trễ chấp nhận, độ trễ hàng đợi, thời gian xử lý, tỷ lệ trùng lặp, thất bại chữ ký, sơ đồ không hợp lệ, dấu thời gian lỗi thời, và xung đột sắp xếp. Tách biệt sức khỏe giao hàng của nhà sản xuất khỏi sức khỏe xử lý kinh doanh của người tiêu dùng để không có một sự kiện đã được chấp nhận, nhưng thất bại sau đó, không biến mất vào một chỉ số thành công chung.

Cung cấp một cái nhìn quản trị có kiểm soát mà có thể tìm kiếm theo ID sự kiện và hiển thị lịch sử giao hàng đã được redacted. Các nhóm vận hành cần đủ bằng chứng để chẩn đoán một thay đổi trạng thái bị thiếu mà không làm lộ thông tin xác thực hoặc toàn bộ nội dung nhạy cảm.

Danh sách kiểm tra thiết kế Webhook

1. Định nghĩa các loại và ID sự kiện ổn định. Tài liệu xem liệu tải trọng có phải là sự kiện, ảnh chụp nhanh, hay con trỏ.
2. Phiên bản sơ đồ. Đề ra quy tắc tương thích cho các trường tùy chọn mới và các phiên bản sự kiện.
3. Ký các byte thô và siêu dữ liệu độ tươi. Công bố các bước xác minh chính xác và hỗ trợ thay thế bí mật.
4. Thi hành bảo mật điểm cuối. Xác minh quyền sở hữu và chặn các điểm đến SSRF.
5. Chấp nhận idempotently. Sử dụng một ID sự kiện duy nhất và một bản ghi xóa bỏ an toàn giao dịch.
6. Công nhận sau khi chấp nhận bền vững. Di chuyển công việc dài hơn vào hàng đợi.
7. Mong đợi sự lặp lại và sắp xếp lại. Sử dụng các phiên bản tài nguyên và đối chiếu thay vì các giả định theo thứ tự đến.
8. Bỏ qua dữ liệu khả năng quan sát. Giữ các bí mật và các trường tải trọng nhạy cảm ra khỏi nhật ký và công cụ hỗ trợ.

Kết luận

Một webhook biến một sự kiện thành một thông báo HTTP, cung cấp cho các tích hợp các cập nhật độ trễ thấp mà không cần liên tục kiểm tra. Cuộc gọi HTTP là phần dễ dàng. Một thiết kế sản xuất xác minh các chữ ký cơ thể thô, thi hành độ tươi, xóa bỏ theo ID sự kiện, xử lý việc sắp xếp lại, chỉ công nhận sau khi chấp nhận bền vững, xử lý thông qua một hàng đợi, bảo vệ đăng ký điểm cuối khỏi SSRF, và đối chiếu trạng thái quan trọng. Những kiểm soát đó biến một callback thành một ranh giới tích hợp đáng tin cậy.