Bảo trì webhook: dừng worker, vô hiệu hóa hay xóa endpoint?

Nếu chỉ bảo trì hệ thống phía sau, hãy để bộ nhận webhook tiếp tục xác minh và lưu bền vững sự kiện, rồi tạm dừng các worker xử lý chúng. Vô hiệu hóa endpoint UnifyPort chuyển trạng thái sang inactive nhưng giữ cấu hình; xóa sẽ loại bỏ tài nguyên endpoint. Không thao tác nào được tài liệu mô tả là dịch vụ “tạm dừng rồi phát lại phần bị bỏ lỡ”. Hãy chọn theo lớp cần dừng.

Điểm chính

• Khi bảo trì CRM, luồng AI hoặc worker, ưu tiên dừng xử lý nghiệp vụ sau lớp tiếp nhận bền vững.
• Chỉ vô hiệu hóa endpoint khi đó là chủ đích, kèm kế hoạch xử lý khoảng trống giao nhận có thể phát sinh.
• Xóa dành cho việc ngừng sử dụng endpoint, không phải công tắc triển khai tạm thời.
• Trả về 503 không tạo ra khoảng chờ bảo trì: UnifyPort thử lại ngay, không có backoff.

So sánh ba cách kiểm soát

Hàng đầu tiên là khuyến nghị thiết kế ứng dụng. Hai hàng còn lại là thao tác quản lý được UnifyPort công bố.

Cách kiểm soát	Điều thay đổi	Phần bạn vẫn phải quản lý
Dừng worker ứng dụng	Consumer ngừng xử lý; bộ nhận khỏe mạnh vẫn lưu sự kiện	Dung lượng hàng đợi, thời gian lưu, điểm tiếp tục và tính lũy đẳng của tác vụ
Vô hiệu hóa endpoint	Trạng thái thành inactive, tài nguyên vẫn còn	Ghi nhận gián đoạn, kiểm tra kích hoạt lại và điều tra dữ liệu thiếu
Xóa endpoint	Tài nguyên bị loại bỏ	Tạo và kiểm tra endpoint mới nếu cần dùng lại

Tài liệu vô hiệu hóa endpoint quy định POST /v1/webhook-endpoints/{endpoint_id}/deactivate. Tài liệu xóa endpoint quy định DELETE /v1/webhook-endpoints/{endpoint_id}, trả về 204 No Content khi thành công.

Đây là các thao tác trên webhook endpoint. Không coi chúng là đăng xuất tài khoản, dừng runtime hoặc hủy công việc ứng dụng đã nhận. Worker đã lấy một tác vụ vẫn có thể hoàn thành nó; muốn ngăn những tác động đó, ứng dụng cần cơ chế kiểm soát riêng.

Khi nào nên dừng worker?

Giả sử nhóm cần cập nhật tích hợp CRM nhưng vẫn muốn nhận hội thoại LINE và WhatsApp vào hộp thư. Đây là tình huống thiết kế giả định, không phải kết quả của một khách hàng. Nguyên tắc tách lớp tiếp nhận cũng hữu ích khi ứng dụng có thêm Zalo.

Tách đường nhận sự kiện khỏi CRM:

1. Xác minh chữ ký và dấu thời gian bằng các byte gốc của yêu cầu.
2. Kiểm tra sự kiện và ghi nhận bền vững vào kho lưu trữ.
3. Trả về xác nhận thành công.
4. Để worker riêng ghi vào CRM, gọi AI hoặc gửi thông báo.

Trước khi dừng consumer, xác nhận kho tiếp nhận sẽ hoạt động suốt thời gian bảo trì. Đặt giới hạn vận hành cho mức tăng hàng đợi và thời gian lưu, đồng thời phân công người xử lý lỗi lưu trữ. Một mảng trong bộ nhớ không phải bộ đệm bảo trì có thể sống qua lần khởi động lại tiến trình.

Sau triển khai, tiếp tục từ trạng thái xử lý đã được ghi nhận. Không đánh dấu toàn bộ tồn đọng là hoàn tất chỉ vì đầu vào đã trả 2xx. Danh sách kiểm tra tích hợp webhook-first giải thích ranh giới lưu trữ ban đầu; bảo trì cần thêm quyết định riêng về lúc consumer được phép chạy.

Cách này không giải quyết bảo trì chính kho tiếp nhận. Nếu cả bộ nhận và kho lưu trữ phải ngừng hoạt động, hãy chuẩn bị đường tiếp nhận thay thế đã kiểm chứng hoặc chấp nhận và ghi rõ gián đoạn. Không hứa thu thập liên tục khi chưa có thiết kế được xác minh.

Vì sao phản hồi lỗi không phải cơ chế tạm dừng?

Theo hợp đồng giao nhận, lỗi kết nối và phản hồi 408, 429, 5xx được thử lại ngay. retry_policy.max_attempts là số lần thử lại sau yêu cầu đầu tiên, mặc định là ba. Không có backoff và không áp dụng Retry-After. Các 4xx khác dừng giao nhận tự động và đánh dấu sự kiện là dead-lettered.

Vì vậy, liên tục trả 503 trong lúc triển khai có thể làm cạn số lần thử, thay vì chờ dịch vụ sẵn sàng. Trả 200 nhưng bỏ nội dung còn tệ hơn: bạn xác nhận dữ liệu chưa được lưu bền vững. Trạng thái dead-lettered cũng không đồng nghĩa với cam kết cung cấp thao tác phát lại công khai.

Duy trì xác minh chữ ký khi bảo trì. signing_secret rỗng tắt chữ ký, không tạm dừng giao nhận. Nếu cần đổi thông tin xác thực, hãy dùng quy trình luân chuyển signing secret riêng, thay vì gộp thay đổi xác thực với ngừng sử dụng endpoint.

Nếu chủ động vô hiệu hóa, đặt điều kiện khôi phục rõ ràng

Trước khi thay đổi, dùng Lấy cấu hình endpoint để ghi lại ID, URL, trạng thái, sự kiện đăng ký, trạng thái ký và chính sách thử lại. Giữ secret thực trong cấu hình được bảo vệ, không ghi vào nhật ký thay đổi. Liệt kê các luồng phụ thuộc endpoint này.

Vô hiệu hóa endpoint đã chọn rồi đọc lại trạng thái. Ghi thời điểm và kết quả thao tác tách biệt với trạng thái hàng đợi ứng dụng. Tài liệu công khai không bảo đảm mọi yêu cầu đang truyền đã kết thúc, cũng không bảo đảm phát lại sự kiện trong thời gian inactive. Không suy ra hai điều này từ một phản hồi thành công.

Để tiếp tục, dùng Cập nhật endpoint với status: active và cấu hình đã rà soát. Giữ đúng URL, đăng ký sự kiện, chính sách thử lại và secret ký không rỗng. Đừng sao chép cấu hình minh họa inactive hoặc không ký vào môi trường production.

Đọc lại kết quả, xác nhận signing_enabled: true, rồi gửi tin nhắn thử nghiệm có kiểm soát tới tài khoản nhắn tin đã kết nối. Theo dõi sự kiện message.received qua xác minh chữ ký, lưu bền vững và worker đích. Việc này chứng minh đường nhận sự kiện mới hoạt động, không chứng minh dữ liệu trong thời gian inactive đã được khôi phục.

Nếu yêu cầu quản lý bị timeout, kiểm tra endpoint hiện tại trước khi thay đổi tiếp. Giữ thông tin chẩn đoán nhưng không ghi secret. Bộ nhận im lặng không chứng minh thao tác vô hiệu hóa đã hoàn tất; phản hồi kích hoạt lại thành công cũng không chứng minh nghiệp vụ đã chạy đến cuối.

Giới hạn của xóa và khôi phục

Chỉ xóa sau khi xác định tài nguyên không còn cần thiết và ghi nhận các phụ thuộc. Xóa thành công không có phần thân JSON để phân tích. Tạo endpoint thay thế sau này là cấp phát mới, không phải khôi phục các lần giao nhận endpoint cũ đã bỏ lỡ.

Giao diện không chính thức của UnifyPort chuẩn hóa sự kiện được hỗ trợ từ tài khoản nhắn tin, nhưng không cung cấp REST API đọc lịch sử tin nhắn tổng quát hay bảo đảm phát lại payload bị bỏ lỡ. Các cơ chế lịch sử WhatsApp giới hạn không phải bảo đảm khôi phục sau bảo trì trên mọi kênh.

Khi tiếp tục công việc đã lưu, dùng đúng ranh giới chống trùng: lần thử lại của sự kiện thông thường giữ nguyên X-Device-Event-Id; các batch conversation.history cần gộp theo từng tin nhắn, không loại bỏ toàn bộ chỉ bằng header này. Tác vụ nghiệp vụ gửi ra vẫn cần tính lũy đẳng độc lập.

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

Vô hiệu hóa có giữ endpoint không?

Có. Trạng thái chuyển sang inactive, tài nguyên không bị xóa. Nhưng điều đó không bảo đảm lưu tồn đọng hay phát lại sự kiện.

Có thể chỉ dừng luồng AI không?

Có, trong thiết kế ứng dụng: dừng consumer đó và để bộ nhận tiếp tục xác minh, lưu bền vững. Đây không phải tham số API UnifyPort bổ sung.

Có nên xóa rồi tạo lại endpoint mỗi lần triển khai?

Thông thường là không. Bảo trì phía sau nên dừng consumer; nếu cần gián đoạn endpoint thì phải lập kế hoạch rõ ràng. Xóa là quyết định ngừng sử dụng.

Bước tiếp theo và nguồn

Đọc hợp đồng giao nhận webhook và ghi rõ lớp nào thực sự dừng khi bảo trì, trước khi thay đổi cấu hình production.

Tài liệu sản phẩm được kiểm tra ngày 2026-10-06:

• Vô hiệu hóa webhook endpoint
• Cập nhật webhook endpoint
• Xóa webhook endpoint
• Giao nhận, xác nhận và thử lại