Webhook là gì?

API Gửi không có phế liệu có thể gửi kết quả tác vụ đến một điểm cuối webhook đã được cấu hình sau khi một công việc bất đồng bộ hoàn thành.

Một webhook cho phép một dịch vụ thông báo cho ứng dụng của bạn rằng có một điều gì đó đã xảy ra mà không cần chờ ứng dụng của bạn hỏi lại. Một dịch vụ tác vụ có thể báo cáo hoàn thành, một dịch vụ thanh toán có thể báo cáo một khoản phí đã được thanh toán, hoặc một nền tảng triển khai có thể báo cáo một bản xây dựng đã hoàn tất. Nhà sản xuất khởi tạo yêu cầu HTTP đến một URL do người tiêu dùng kiểm soát. Ứng dụng của bạn nhận tin nhắn, quyết định có chấp nhận hay không, và sau đó cập nhật trạng thái của chính nó.

Định nghĩa ngắn gọn che giấu một số lựa chọn kỹ thuật. Một sự kiện có thể đến sau khi hành động của người dùng ban đầu đã kết thúc, và một xác nhận mạng có thể bị mất ngay cả khi xử lý thành công. Một thiết kế webhook hữu ích do đó bao gồm xác thực, lưu trữ, loại bỏ trùng lặp, sắp xếp và phục hồi. Hướng dẫn này theo dõi một thông báo từ đăng ký đến biên nhận và giải thích nơi mà một người nhận nên tin tưởng vào chứng cứ thay vì giả định.

Hợp đồng Nhà sản xuất, Sự kiện và Người nhận

Ba vai trò làm cho việc trao đổi webhook dễ hiểu. Nhà sản xuất sở hữu sự kiện, bản ghi sự kiện mô tả những gì đã xảy ra, và người nhận cung cấp một điểm cuối có thể tiếp cận. Nhà sản xuất cần một URL điểm cuối và thường là một đăng ký xác định các sự kiện nào sẽ gửi. Người nhận cần biết phương thức yêu cầu mong đợi, tiêu đề, hình dạng payload và phản hồi xác nhận. Quy chuẩn ngữ nghĩa HTTP định nghĩa khung yêu cầu và phản hồi; hợp đồng nhà cung cấp cung cấp ý nghĩa của sự kiện.

Hãy tưởng tượng một công việc cào được xác định bằng ID tác vụ. Đơn gửi có thể trả về trước khi việc thu thập kết thúc. Sau đó, một tin nhắn hoàn thành có thể mang theo ID đó và một trạng thái. Người nhận sử dụng ID để liên kết sự kiện với bản ghi công việc đã lưu trữ. Nó không nên giả định rằng mọi payload đều nhúng toàn bộ tập dữ liệu cuối cùng; một số dịch vụ gửi một con trỏ, trong khi những dịch vụ khác bao gồm kết quả. Giữ ID tác vụ gốc khi gửi để kết hợp sau này không phụ thuộc vào một URL đã đoán trước hoặc nhãn hiển thị.

Chu trình cuộc sống tác vụ AI Scraper hiện tại tài liệu một URL webhook tùy chọn và ID tác vụ được đẩy, trạng thái, đầu vào, và kết quả tác vụ tùy chọn. Đó là một hợp đồng cụ thể, không phải là một lược đồ webhook phổ quát. Một người nhận được xây dựng cho một sản phẩm khác phải kiểm tra tài liệu của sản phẩm đó. Ngay cả trong một nền tảng, hai họ sự kiện có thể sử dụng các tên trường và trạng thái hoàn thành khác nhau.

Giao hàng Webhook so với Polling

Polling yêu cầu một dịch vụ cho trạng thái theo lịch trình. Một webhook thay đổi hướng của bước đầu tiên: nguồn liên lạc với điểm cuối của bạn khi nó có một sự kiện liên quan. Điều này có thể giảm việc kiểm tra trống và rút ngắn thời gian chờ trước khi quy trình làm việc của bạn nhận thấy một thay đổi. Nó cũng thêm một người nhận công khai, sự không chắc chắn về giao hàng mạng và công việc bảo mật mới. Cả hai kiểu đều không làm cho sự kiện kinh doanh cơ bản trở thành giao dịch giữa hai hệ thống hoạt động độc lập.

Một kiến trúc thực tiễn thường kết hợp một webhook để phản ứng nhanh với một kiểm tra trạng thái định kỳ để hòa giải. Kiểm tra theo lịch trình so sánh các công việc địa phương với trạng thái tác vụ ủy quyền của nhà cung cấp và tìm các thông báo bị thiếu hoặc sai sót trong xử lý địa phương. Giữ cho việc kiểm tra này hẹp: chỉ truy vấn các công việc mà trạng thái địa phương của chúng chưa đạt đến trạng thái đầu cuối đáng tin cậy. Người nhận và người hòa giải nên gọi cùng một chức năng chuyển trạng thái idempotent hơn là tạo ra hai con đường mâu thuẫn.

Sự lựa chọn phụ thuộc vào độ nhạy cảm về thời gian và các tính năng của nhà cung cấp. Nếu một kết quả phải được xử lý ngay sau khi hoàn thành và nhà cung cấp tài liệu các callback, một webhook là hữu ích. Nếu người tiêu dùng không có điểm cuối HTTPS có thể truy cập hoặc nhà cung cấp không có cơ chế giao hàng, polling có thể đơn giản hơn. Đối với các tin nhắn tương tác qua lại, một kết nối liên tục có thể phù hợp hơn. Tên webhook không hứa hẹn bất kỳ độ trễ hoặc độ bền nào cụ thể.

Cách chấp nhận một thông báo một cách an toàn

Xem một yêu cầu HTTP đến là đầu vào không tin cậy. Đầu tiên giới hạn kích thước và phương thức của nó, yêu cầu lộ trình dự kiến, và chỉ phân tích loại media được ghi lại. Sau đó áp dụng phương pháp xác thực của nhà cung cấp. Nếu nhà cung cấp ký các payload, kiểm tra phải sử dụng các byte thô chính xác và các tiêu đề chữ ký được ghi lại trước khi trình phân tích JSON thay đổi đại diện. Quy định Tiêu chuẩn Webhook mô tả một mô hình sự kiện ký kết chung, nhưng một nhà sản xuất phải thực sự triển khai nó trước khi người nhận có thể dựa vào mô hình đó.

Kiểm tra chữ ký trả lời liệu một người nắm giữ bí mật ký kết có sản xuất những byte đó hay không. Điều này không chứng minh rằng sự kiện là mới, rằng payload khớp với đăng ký của bạn, hoặc rằng tác vụ thuộc về tài khoản của bạn. Kiểm tra dấu thời gian hoặc siêu dữ liệu phát lại khi nhà cung cấp cung cấp chúng; ánh xạ ID tác vụ tới một công việc địa phương; xác thực các trường cần thiết và các chuyển tiếp trạng thái được phép. Giữ bí mật trong một kho lưu trữ bí mật được quản lý và sử dụng so sánh thời gian cố định khi sơ đồ xác thực mà bạn chọn yêu cầu so sánh các giá trị xác thực tin nhắn.

Hãy chính xác về hành vi Scrapeless. Vòng đời AI Scraper được tài liệu hóa xác định yêu cầu về payload callback và URL HTTPS, nhưng bản thân nó không xác định rằng callback này sẽ mang một tiêu đề chữ ký cụ thể. Xây dựng người nhận từ hợp đồng giao hàng hiện tại của sản phẩm đã chọn. Nếu chi tiết xác thực không được tài liệu hóa cho gia đình sự kiện đó, hãy hỏi bộ phận hỗ trợ hoặc sử dụng một bí mật do ứng dụng kiểm soát chỉ trong URL người nhận nếu nhà cung cấp rõ ràng hỗ trợ thiết kế đó và đánh giá bảo mật của bạn chấp nhận rủi ro phơi bày của nó.

Biên nhận, Xếp hàng và Xử lý Idempotent

Bộ xử lý HTTP nên làm đủ công việc để đảm bảo biên nhận bền vững và sau đó xác nhận bằng cách sử dụng phản hồi thành công được tài liệu hóa của nhà cung cấp. Một chuỗi phổ biến là xác thực yêu cầu, ghi lại một ID sự kiện hoặc ID tác vụ với payload thô và thời gian biên nhận, xếp hàng một công việc xử lý, sau đó phản hồi. Các biến đổi dữ liệu dài bên trong đường dẫn yêu cầu nâng cao cơ hội nhà sản xuất nhìn thấy thời gian chờ ngay cả khi cập nhật cơ sở dữ liệu của bạn cuối cùng đã thành công. Sự mơ hồ đó là lý do tại sao xử lý doanh nghiệp cần một bộ bảo vệ trùng lặp.

Chọn một khóa loại bỏ trùng lặp từ hợp đồng nhà cung cấp. Một ID sự kiện ổn định là lý tưởng khi nó tồn tại. Nếu nhà sản xuất chỉ công bố ID tác vụ cộng với trạng thái cuối cùng, hãy xây dựng một khóa ứng dụng từ những trường được tài liệu hóa đó và phạm vi đăng ký hoặc tài khoản. Thêm một ràng buộc duy nhất của cơ sở dữ liệu xung quanh khóa đó. Người tiêu dùng sau đó có thể chấp nhận cùng một thông báo nhiều hơn một lần trong khi áp dụng hiệu ứng kinh doanh chỉ một lần. Đừng dựa vào một tập trong bộ nhớ bị biến mất khi quy trình khởi động lại.

Một tác vụ cũng có thể thay đổi trạng thái trước khi các tin nhắn tới. Ví dụ, một thông báo hoàn thành có thể được xử lý sau khi một kiểm tra trạng thái riêng biệt đã đánh dấu công việc là hoàn thành. Hàm chuyển tiếp nên so sánh trạng thái hiện tại và trạng thái tới và từ chối bất kỳ thay đổi nào sẽ đưa một công việc đã hoàn thành trở lại. Lưu giữ payload gốc và quyết định để một điều hành viên có thể giải thích lý do tại sao một tin nhắn được chấp nhận, bị bỏ qua như một bản sao hoặc bị từ chối như không hợp lệ.

Đăng ký, Thất bại và Tính quan sát

Chỉ đăng ký một URL người nhận mà bạn kiểm soát. Giữ cho đường dẫn có tính mục đích cụ thể và tránh phơi bày các địa chỉ nội bộ như là đích đến callback. Một ứng dụng cho phép người dùng tùy ý đăng ký các điểm cuối webhook có thể trở thành một kênh giả mạo yêu cầu phía máy chủ nếu nó lấy các mục tiêu mạng riêng tư. Xác thực chính sách lược đồ và đích đến khi đăng ký, và kiểm tra lại các địa chỉ đã giải quyết khi giao hàng xảy ra nếu hệ thống của bạn là nhà sản xuất. Hướng dẫn OWASP SSRF giải thích ranh giới mạng đứng sau rủi ro này.

Ghi lại bằng chứng giao hàng tại người tiêu dùng: thời gian nhận, ID tác vụ hoặc sự kiện của nhà cung cấp, phiên bản lược đồ khi cung cấp, quyết định xác thực, trạng thái xác nhận, ID hàng đợi và trạng thái xử lý cuối cùng. Ngoại trừ các bí mật và dữ liệu cá nhân không cần thiết cho hoạt động. Một bảng điều khiển chỉ nói “webhook đã thành công” không thể phân biệt giao hàng HTTP từ việc lưu trữ phía hạ nguồn thành công. Tách các phép đo đó và cảnh báo về các sự kiện chấp nhận bị tạm dừng.

Kiểm tra quy trình làm việc với một sự kiện vô hại trước khi phụ thuộc vào nó. Xác nhận rằng người nhận có thể tiếp cận qua HTTPS, rằng một payload hợp lệ thực hiện chuyển tiếp trạng thái như mong đợi, rằng các payload không hợp lệ bị từ chối và rằng việc giao hàng lặp lại không thay đổi thêm trạng thái doanh nghiệp nào khác. Mô phỏng một thông điệp không theo thứ tự nếu nhà cung cấp có thể gửi nhiều sự kiện cho một đối tượng. Những kiểm tra này thực hiện hợp đồng người nhận mà không giả định nhà sản xuất đảm bảo thứ tự hoặc giao hàng đúng một lần.

Khi một Webhook Là Công Cụ Sai

Một webhook rất phù hợp cho những thay đổi riêng biệt có ý nghĩa đối với một hệ thống khác. Nó không phù hợp khi đọc một tài nguyên hiện tại theo yêu cầu. Nếu một người dùng mở bảng điều khiển và yêu cầu số dư tài khoản mới nhất, một truy vấn API thông thường rõ ràng hơn là chờ thông báo trước đó. Một webhook có thể báo hiệu rằng số dư đã thay đổi, trong khi API vẫn là nơi để đối chiếu giá trị chính thức.

Các luồng sự kiện có khối lượng cao cũng có thể cần các tính năng môi giới mà một người nhận HTTP tách biệt không cung cấp, chẳng hạn như thứ tự phân vùng và phát lại theo offset. Một nhà sản xuất webhook có thể cung cấp nhật ký giao hàng riêng, nhưng đó là một tính năng riêng của nhà cung cấp, không phải là phần của khái niệm cơ bản. Sử dụng cơ chế nhỏ nhất đáp ứng khối lượng sự kiện, mức độ chậm trễ chấp nhận, và yêu cầu phục hồi.

Đối với các công việc Scrapeless, giữ callback gắn với một tác vụ không đồng bộ được tài liệu hóa. Scraping API là một bề mặt sản phẩm cho dữ liệu web có cấu trúc, trong khi hướng dẫn quy trình diễn viên liên quan giải thích tại sao ID tác vụ và xử lý kết quả lại quan trọng. Định nghĩa chính xác hành động địa phương nào một tác vụ hoàn thành kích hoạt, và giữ lại một đường dẫn tra cứu trạng thái để kiểm toán hành động đó sau này.

Kết luận

Một webhook là một cuộc gọi HTTP kích hoạt sự kiện từ một nhà sản xuất đến một người nhận. Đơn vị đáng tin cậy là toàn bộ hợp đồng: đăng ký, biên nhận được xác thực, xác nhận bền vững, kiểm soát sao chép, chuyển tiếp trạng thái và đối chiếu. Bắt đầu với một sự kiện được tài liệu hóa và một kết quả địa phương có thể đo lường trước khi mở rộng người nhận đến các gia đình sự kiện bổ sung.