Webhook so với API: Push, Polling và Khi nào sử dụng từng cái

Lời khuyên phổ biến về webhook so với API là chưa đầy đủ: hãy dùng webhooks cho các cập nhật theo thời gian thực và API cho mọi thứ khác. Điều đó bỏ qua phần khó nhất. Một bộ nhận webhook là một trình tiêu thụ tin nhắn bất đồng bộ, và việc chọn hình thức gửi đẩy (push delivery) có nghĩa là chấp nhận trách nhiệm về các bản sao trùng lặp, thông báo bị bỏ lỡ, xác thực và phục hồi. Sự so sánh hữu ích không phải là đẩy so với kéo. Đó là kinh tế lưu lượng truy cập so với kiểm soát hoạt động, với một đường dẫn phục hồi cho bất kỳ kênh nào bị lỗi.

Mục lục

• Tổng quan về Webhook và API
  • Tách lệnh khỏi thông báo
• Cách mỗi mô hình di chuyển dữ liệu
  • Streaming giải quyết một vấn đề khác
• Những đánh đổi về độ tin cậy bạn phải thiết kế
  • Ghép nối từng lỗi với một biện pháp bảo vệ
  • Xác nhận là một ranh giới về độ bền
• Khi Polling là lựa chọn an toàn hơn
  • Nhận ra những ràng buộc ưu tiên Polling
• Cách xây dựng luồng Hybrid cho các công việc truyền thông
  • Thiết lập quyền sở hữu bền vững cho tác vụ
  • Hội tụ về hoàn thành có thẩm quyền
• Chọn theo khối lượng công việc và ràng buộc
  • Sử dụng tổng chi phí vận hành làm yếu tố quyết định

Webhook vs API Sơ lược

Webhook là một cơ chế phân phối sự kiện được xây dựng trên các API HTTP, không phải là một sự thay thế cho chúng. Hầu hết các tích hợp sản xuất đều cần cả hai: một đường dẫn yêu cầu cho các lệnh và đọc dữ liệu chính xác, cộng với một đường dẫn thông báo cho các thay đổi.

Giả sử ứng dụng của bạn gửi một công việc tạo video. Với API, backend của bạn gửi một yêu cầu GET sử dụng định danh tác vụ đã lưu và nhận trạng thái hiện tại của công việc. Ứng dụng của bạn chọn thời điểm hỏi, thời gian chờ đợi và phải làm gì nếu yêu cầu thất bại.

Với webhook, nhà cung cấp gửi một sự kiện hoàn thành công việc đến một endpoint mà bạn đã đăng ký. Backend của bạn chấp nhận thông báo đó và lên lịch cho hành động tiếp theo, chẳng hạn như truy xuất tài sản đã hoàn thành. Phiên trình duyệt ban đầu không cần phải duy trì kết nối.

Tách lệnh khỏi thông báo

Gửi công việc và biết rằng nó đã hoàn thành là các hoạt động khác nhau. Một API có thể chấp nhận một tác vụ ngay lập tức mà không cần giữ kết nối mở cho đến khi quá trình tính toán cơ bản hoàn tất. Webhook sau đó cung cấp một tín hiệu hoàn thành riêng biệt.

Sự phân biệt đó ngăn chặn một lỗi thiết kế phổ biến: coi mọi hoạt động không đồng bộ như một yêu cầu HTTP phải duy trì mở. Nó cũng ngăn chặn lỗi ngược lại, cố gắng sử dụng thông báo sự kiện như một bản ghi hoàn chỉnh về trạng thái hiện tại.

Quyết định đầu tiên: Ứng dụng của bạn có cần phản ứng khi có gì đó thay đổi, hay nó chỉ cần câu trả lời khi ai đó hỏi?

Nếu người dùng mở màn hình lịch sử công việc, hãy tìm nạp các bản ghi hiện tại. Nếu một công việc đã hoàn thành nên kích hoạt việc phân phối tài sản trong khi không ai đang xem màn hình đó, hãy sử dụng một đường dẫn dựa trên sự kiện. Cả hai mô hình đều không loại bỏ nhu cầu xử lý lỗi mạng, nhưng mỗi mô hình đặt người gọi vào một vị trí khác nhau để khôi phục.

Cách Mỗi Kiểu Di chuyển Dữ liệu

Với polling, client lặp lại yêu cầu trạng thái theo một bộ đếm thời gian, bất kể có gì thay đổi hay không. Với một webhook, nhà cung cấp khởi tạo yêu cầu sau một sự kiện, vì vậy lưu lượng thông báo đi theo hoạt động thay vì đồng hồ.

Hướng dẫn so sánh webhook và polling của Nylas đưa ra các ví dụ về lưu lượng cơ bản: polling một tài nguyên mỗi 60 giây có nghĩa là 1,440 yêu cầu mỗi ngày, trong khi so sánh của nó về 10,000 tài khoản tạo ra 2.88 triệu yêu cầu polling hàng ngày so với khoảng 500,000 lượt gửi webhook.

Lưu lượng và độ trễ theo khoảng thời gian polling và tốc độ sự kiện

Các mức trung bình của polling giả định rằng các thay đổi xảy ra độc lập với lịch trình polling. Chúng mô tả thời gian chờ đợi cho đến lần kiểm tra tiếp theo, chứ không phải thời gian nhà cung cấp dành để thực hiện công việc.

Khoảng thời gian ngắn hơn cải thiện thời gian phát hiện bằng cách tốn nhiều yêu cầu hơn. Khoảng thời gian dài hơn giảm lưu lượng nhưng khiến công việc đã hoàn thành nằm đó mà không được phát hiện. Ở quy mô tài khoản, ngay cả một lịch trình khiêm tốn cũng tạo ra lưu lượng đáng kể vì mọi tài khoản không hoạt động vẫn được kiểm tra.

Gửi webhook loại bỏ lịch kiểm tra cố định đó, nhưng số lượng lượt gửi không phải là toàn bộ chi phí hạ tầng. Các tra cứu API sau thông báo, thử lại gửi, lưu trữ của bộ nhận và thực thi của worker vẫn tiêu tốn tài nguyên.

Đây là các mô hình giao tiếp riêng biệt, không phải là các nhãn có thể thay thế cho nhau.

Streaming giải quyết một vấn đề khác

Một phản hồi văn bản streaming giữ yêu cầu mở và trả về các token khi chúng được tạo. Đối với một trợ lý lập trình tương tác, thời gian đến token đầu tiên và tính liên tục của đầu ra quan trọng hơn việc nhận một callback hoàn thành riêng biệt.

Các phản hồi văn bản của chúng tôi streaming từng token, trong khi các tác vụ hình ảnh và video trả về một tác vụ mà bạn polling hoặc nhận thông báo webhook khi sẵn sàng. Tài liệu API media là điểm khởi đầu để triển khai đường dẫn yêu cầu định hướng tác vụ đó.

Ước tính tốc độ sự kiện của bạn cho mỗi tài nguyên trước khi chọn khoảng thời gian polling. Một tài nguyên ít hoạt động và một tài nguyên thay đổi liên tục không nên tự động chia sẻ cùng một lịch trình.

Đối với polling, các khoảng thời gian ngắn hơn đánh đổi nhiều lưu lượng hơn để có độ trễ phát hiện ít hơn. Webhooks tránh sự đánh đổi cụ thể đó, nhưng thay thế nó bằng chi phí vận hành một bộ nhận đáng tin cậy.

Những đánh đổi về độ tin cậy bạn phải thiết kế để xử lý

Việc gửi webhook thường là ít nhất một lần, chứ không phải chính xác một lần. Điều này mô tả mô hình gửi, không phải lời hứa rằng nhà cung cấp sẽ thử lại mãi mãi. Các lần thử lại có giới hạn vẫn có thể kết thúc bằng một sự kiện không được gửi, vì vậy hãy thiết kế bộ nhận cho trường hợp xấu nhất thay vì trường hợp lý tưởng.

Một timeout không cho người gửi biết điều gì đã xảy ra ở phía sau. Bộ nhận của bạn có thể đã ghi sự kiện vào bộ nhớ, sau đó mất xác nhận trên mạng. Khi người gửi thử lại, ứng dụng của bạn nhận được cùng một sự kiện một lần nữa và phải xử lý nó một cách khéo léo.

Đối phó từng loại lỗi bằng biện pháp bảo vệ phù hợp

• Gửi trùng lặp: Lưu trữ một định danh sự kiện ổn định dưới một ràng buộc duy nhất. Khi các nhà cung cấp phân biệt sự kiện với các lần thử gửi, hãy loại bỏ trùng lặp quá trình xử lý nghiệp vụ bằng định danh sự kiện, không phải bằng định danh lần thử.
• Tác dụng phụ lặp lại: Làm cho việc xuất bản tài sản, cập nhật tài khoản và thông báo cho khách hàng trở nên idempotent. Việc loại bỏ trùng lặp đầu vào không có tác dụng gì đối với một worker bị lỗi sau khi thực hiện hành động nhưng trước khi ghi nhận thành công.
• Sự kiện không theo thứ tự: Kiểm tra trạng thái có thẩm quyền hoặc phiên bản tài nguyên được ghi lại trước khi áp dụng một chuyển đổi. Một sự kiện "đang xử lý" bị trì hoãn không bao giờ được ghi đè lên một tác vụ đã hoàn thành.
• Xử lý chậm: Xác minh, chấp nhận bền vững và xác nhận sự kiện trước khi giao công việc tốn kém cho một queue worker.

Các chính sách thử lại của nhà cung cấp không thể thay thế cho nhau. Tài liệu webhook của Supabase yêu cầu phản hồi 2xx trong vòng 20 giây, sử dụng exponential backoff và dừng lại sau năm lần thử không thành công. Hướng dẫn đảm bảo gửi của Svix ghi lại lần thử ban đầu của Dynamic cộng với năm lần thử lại trong khoảng một ngày, cùng với các quy tắc thử lại cụ thể theo trạng thái của Glean.

Hành vi thử lại webhook được ghi nhận bởi nhà cung cấp

Xác nhận là một ranh giới về độ bền

Việc trả về thành công trước khi lưu trữ bền vững tạo ra một loss window: người gửi ngừng thử lại, nhưng ứng dụng của bạn không có gì có thể khôi phục được. Việc trả về thành công chỉ sau khi xử lý phương tiện tạo ra vấn đề ngược lại: timeouts không cần thiết và gửi trùng lặp. Xác nhận việc chấp nhận bền vững, không phải công việc nghiệp vụ đã hoàn thành.

Xác minh chữ ký phải được thực hiện trước khi tin tưởng vào payload. Giữ nguyên raw request body khi lược đồ chữ ký yêu cầu, và tuân theo quy trình xác minh được ghi lại của nhà cung cấp thay vì ký một reserialized object.

Thêm dead-letter handling cho các lần thử lại của worker đã cạn kiệt và delivery observability kết nối các event ID, task ID, lỗi xác nhận và kết quả xử lý. Đối với polling leg của cùng một workflow, hãy phân loại các lỗi bằng các status code được trả về: API của UberLLM từ chối các cuộc gọi với error code như 402, 404, 429 và 503, điều này cho phép một reconciliation job phân biệt việc từ chối thanh toán với throttling hoặc một người bán tạm thời không khả dụng.

Một lần poll bị bỏ lỡ được khôi phục bằng cách kiểm tra lại. Một webhook bị bỏ lỡ cần một lần gửi khác hoặc một reconciliation pass độc lập đọc lại trạng thái tác vụ có thẩm quyền theo lịch trình. Hãy xây dựng pass đó cho dù bạn có expose một receiver hay không; đó là điều biến việc gửi at-least-once thành xử lý effective exactly-once.

Khi Polling là lựa chọn an toàn hơn

Webhooks là một vấn đề về độ tin cậy trong việc phân phối, chứ không chỉ là một API nhanh hơn. Nếu ứng dụng của bạn không thể hỗ trợ hợp đồng nhận, polling có thể là lựa chọn đáng tin cậy hơn.

Sự khác biệt trong vận hành dễ thấy nhất ở ranh giới của người tiêu dùng (consumer).

Một desktop agent, một công cụ nội bộ phía sau tường lửa, hoặc một CI runner tạm thời có thể có quyền truy cập ra ngoài mà không có địa chỉ inbound ổn định. Việc khiến các client đó nhận callback có thể yêu cầu một dịch vụ lưu trữ bổ sung, xác thực giữa các thành phần và một quá trình chuyển giao bền vững trở lại người gọi ban đầu. Đó là hạ tầng, chứ không phải một thay đổi cấu hình nhỏ.

Nhận biết các ràng buộc ủng hộ polling

• Không có endpoint công khai ổn định: Giữ giao tiếp hướng ra ngoài thay vì để lộ một môi trường phát triển tạm thời.
• Không có consumer sự kiện bền vững: Thăm dò trạng thái đáng tin cậy trong khi bạn xây dựng bộ nhớ và xử lý an toàn. Một bộ nhận mà quên các sự kiện đã chấp nhận thì không phải là một cải tiến.
• Phục hồi do consumer kiểm soát: Lên lịch kiểm tra theo giới hạn đồng thời, cửa sổ bảo trì và thời hạn ứng dụng của riêng bạn.

Giả sử một công cụ xây dựng trên máy tính xách tay của nhà phát triển gửi một tác vụ media từ xa. Nó có thể kiểm tra định kỳ cho đến khi hoàn thành, dừng lại khi nhà phát triển hủy bỏ và tiếp tục từ mã định danh tác vụ đã lưu. Đối với một số lượng nhỏ các công việc đang hoạt động, điều đó có thể đơn giản và rẻ hơn so với việc duy trì một bộ nhận luôn sẵn sàng.

Polling vẫn cần kỷ luật. Giảm tần suất khi gặp lỗi tạm thời, tránh đồng bộ hóa các lần kiểm tra của mọi client và ngừng kiểm tra các tác vụ đã kết thúc. Một cơn bão thử lại cũng có thể xảy ra với các yêu cầu outbound.

Video đi kèm cung cấp một cách khác để hình dung sự khác biệt giữa yêu cầu và callback.

Hãy chọn mô hình mà consumer của bạn có thể phục hồi một cách đáng tin cậy, chứ không phải mô hình có bản demo thành công nhanh nhất.

Lưu lượng webhook inbound bổ sung các yêu cầu về bảo mật endpoint, kiểm tra chữ ký, xếp hàng, loại bỏ trùng lặp và tính khả dụng. Polling mang lại cho bạn quyền kiểm soát rõ ràng về thời điểm hoạt động tiếp theo diễn ra, mặc dù giới hạn tốc độ của nhà cung cấp vẫn áp dụng.

Sử dụng webhook với cơ chế polling dự phòng khi việc phân phối inbound là khả thi và các sự kiện thường xuyên cần đến nó; nếu không, hãy polling với nhịp độ, đồng thời và thời gian chờ của riêng bạn.

Cách Xây Dựng Luồng Lai cho Các Tác Vụ Truyền Thông

Một tích hợp lai xem các callback như lời nhắc để kiểm tra công việc, chứ không phải là bằng chứng duy nhất cho thấy công việc tồn tại. Định danh tác vụ được duy trì kết nối yêu cầu khởi tạo, thông báo đến, kiểm tra phục hồi và kết quả cuối cùng của khách hàng.

Chúng tôi sử dụng theo dõi tác vụ không đồng bộ và các callback webhook để duy trì các quy trình làm việc truyền thông khối lượng lớn. Đối với các tác vụ hình ảnh và video, việc theo dõi đó có nghĩa là một sự gián đoạn ở một người bán sẽ không làm mất tác vụ của khách hàng.

Quy trình làm việc giữ riêng biệt việc gửi, thông báo và phục hồi trạng thái.

Thiết lập quyền sở hữu bền vững của tác vụ

1. Gửi qua API và lưu ID tác vụ được trả về. Duy trì nó với trạng thái đã xếp hàng trước khi bắt đầu công việc tiếp theo. Tạo một bản ghi gửi cục bộ trước đó nếu có thể, vì một callback nhanh có thể vượt qua phản hồi gửi. Lỗi thường gặp là giả định các callback luôn đến sau khi cơ sở dữ liệu đã commit. Giữ lại các sự kiện không khớp để liên kết sau này.

2. Đăng ký một bộ nhận mà bền vững xếp hàng các sự kiện đã chấp nhận. Giữ cho trình xử lý yêu cầu nhỏ gọn và xác nhận kịp thời sau khi chấp nhận an toàn. Không trả về thành công trước khi lưu trữ, và không tải xuống hoặc chuyển đổi tài sản đã hoàn thành bên trong trình xử lý.

3. Xác minh tính xác thực, sau đó loại bỏ trùng lặp xử lý. Xác minh chữ ký phải diễn ra tại điểm vào trước khi một sự kiện được tin cậy hoặc xác nhận; sau đó worker kiểm tra định danh sự kiện được duy trì trước khi áp dụng các hiệu ứng. Lỗi thường gặp là coi những điều này như việc dọn dẹp tùy chọn sau khi xử lý. Giữ riêng biệt trạng thái chấp nhận và xử lý để một worker bị gián đoạn có thể tiếp tục an toàn.

Hội tụ về hoàn thành chính thức

4. Lấy trạng thái chính thức của tác vụ. Sử dụng ID tác vụ đã lưu trước khi đánh dấu tác vụ của khách hàng là hoàn thành. Một sự kiện có thể chỉ chứa một định danh, và một thông báo bị trì hoãn có thể mô tả một chuyển đổi cũ hơn. Đối với một triển khai chỉnh sửa hình ảnh, hướng dẫn API chỉnh sửa ảnh](https://uberllm.dev/guides/photo-editing-api) cung cấp một quy trình làm việc yêu cầu cụ thể để xây dựng.

5. Thăm dò các tác vụ vẫn đang chờ xử lý vượt quá khung thời gian dự kiến của chúng. Sử dụng backoff, jitter và số lần thử tối đa cho mỗi chu kỳ kiểm tra. Không gửi lại việc tạo một cách mù quáng khi thiếu callback, vì tác vụ gốc có thể đã hoàn thành.

6. Đặt thời hạn ứng dụng và đối chiếu các tác vụ cũ hàng ngày. Phân biệt một lần tạo thất bại với một lỗi kiểm tra trạng thái. Nếu trạng thái nhà cung cấp vẫn không xác định tại thời hạn của bạn, ghi lại một kết quả phục hồi hoặc thất bại rõ ràng thay vì để giao diện khách hàng bị xếp hàng vô thời hạn.

Kiểm tra sức khỏe: Mọi ID tác vụ đã lưu phải dẫn đến một kết quả ứng dụng cuối cùng, hoàn thành hoặc thất bại, trong thời gian chờ của bạn. Giữ trạng thái nhà cung cấp chưa được giải quyết hiển thị cho người vận hành để thời gian chờ ứng dụng không bỏ qua một kết quả vẫn cần phục hồi.

Chọn theo Khối lượng công việc và Ràng buộc

Bắt đầu với khối lượng công việc, sau đó loại bỏ bất kỳ mô hình nào mà triển khai của bạn không thể hỗ trợ. Cơ chế thông báo nhanh nhất sẽ không hữu ích nếu máy khách nhận không thể chấp nhận các yêu cầu đến hoặc nhóm không thể khôi phục quá trình xử lý bị gián đoạn.

Ánh xạ khối lượng công việc với mô hình

Một trình duyệt vẫn có thể nhận các bản cập nhật ứng dụng thông qua backend của riêng nó, nhưng backend đó sở hữu bộ nhận webhook. Đừng đặt thông tin xác thực của nhà cung cấp hoặc bí mật xác minh callback vào trình duyệt để bỏ qua trách nhiệm đó.

Khối lượng công việc và ràng buộc triển khai nên được đánh giá cùng nhau.

Sử dụng tổng chi phí vận hành làm yếu tố quyết định

Một phân tích được trích dẫn trong bài viết về kiến trúc webhook của Xictron cho thấy chỉ có 1.5% trong số 30 triệu yêu cầu polling trả về một bản cập nhật. Điều đó minh họa cách polling được điều chỉnh kém có thể lãng phí lưu lượng truy cập, chứ không phải mọi tích hợp webhook đều sẽ tốn ít chi phí hơn.

So sánh khoảng thời gian polling, tần suất sự kiện, kích thước payload và giới hạn của nhà cung cấp với chi phí lưu trữ bộ nhận, lưu trữ hàng đợi, giám sát và phản hồi sự cố. Đồng thời tính cả số lần đọc API mà worker webhook của bạn vẫn cần. Một thông báo nhẹ nhàng theo sau bởi một lần tìm nạp có thẩm quyền không phải là một kiến trúc không có yêu cầu.

Đối với một ứng dụng đa nhà cung cấp, hãy kiểm tra tính nhất quán của event-schema và hành vi dự phòng. Việc chuẩn hóa trạng thái tác vụ vào mô hình ứng dụng của riêng bạn có thể quan trọng hơn những khác biệt nhỏ về tốc độ thông báo.

Quy tắc lựa chọn: Ưu tiên đường dẫn chính đơn giản nhất đáp ứng yêu cầu của người dùng, sau đó tài trợ cho đường dẫn khôi phục trước khi tối ưu hóa độ trễ.

Sử dụng API khi ứng dụng cần câu trả lời cho một yêu cầu. Sử dụng webhooks khi nó phải phản ứng với các thay đổi và có thể vận hành một bộ nhận an toàn, bền vững. Thêm các kiểm tra trạng thái độc lập cho các công việc chạy dài, và giữ polling do consumer kiểm soát khi không thể gửi đến.

Trước khi triển khai, hãy ghi lại tốc độ sự kiện dự kiến của bạn cho mỗi tài nguyên, liệu bạn có thể hiển thị một endpoint ổn định hay không và cách bạn sẽ xử lý việc xử lý trùng lặp. Sau đó, thực hiện một yêu cầu API đơn giản và xác minh rằng bạn có thể lưu và truy xuất tác vụ kết quả trước khi thêm các callback.

---

UberLLM cung cấp tất cả các mô hình thông qua một API key và chấp nhận các định dạng wire của OpenAI và Anthropic, vì vậy các máy khách hiện có thể sử dụng base URL và thông tin xác thực phù hợp. Đối với các quy trình làm việc về hình ảnh và video, hãy chọn task polling hoặc thông báo webhook khi kết quả đã sẵn sàng. Truy cập UberLLM để kiểm tra đường dẫn yêu cầu, sau đó thêm các đường dẫn hoàn thành và khôi phục mà ứng dụng của bạn cần.