← Tất cả bài viết
Cẩm nang

Webhook tài khoản UnifyPort: Vì sao workspace không nhận được sự kiện?

Nếu Webhook workspace của UnifyPort nhận sự kiện từ các tài khoản nhắn tin khác nhưng thiếu một tài khoản cụ thể, hãy kiểm tra cấu hình Webhook độc lập của tài khoản đó. Cấu hình tài khoản được ưu tiên thay cho cấu hình workspace. Endpoint riêng ở trạng thái inactive hoặc không đăng ký sự kiện cần nhận đều không khiến hệ thống tự chuyển sự kiện sang workspace. Xóa endpoint độc lập cuối cùng sẽ khôi phục kế thừa cho các lần gửi đầu tiên sau đó, không phải gửi lại sự kiện cũ.

Điểm chính

  • Endpoint workspace và endpoint tài khoản thuộc hai phạm vi cấu hình, không phải cặp chính–dự phòng.
  • Phải đọc cả hai danh sách: truy vấn không chỉ định tài khoản chỉ trả về endpoint workspace.
  • Danh sách tài khoản rỗng nghĩa là không có cấu hình độc lập, không có nghĩa là không có đường nhận sự kiện.
  • Vô hiệu hóa vẫn giữ cấu hình ưu tiên; cần xóa endpoint độc lập cuối cùng để khôi phục kế thừa.
  • Kiểm tra định tuyến, đăng ký sự kiện, chữ ký và trạng thái kết nối ở các bước riêng biệt.

Cấu hình nào quyết định nơi nhận sự kiện?

Tài liệu tạo Webhook endpoint định nghĩa trường account_id tùy chọn trong body. Khi có trường này, endpoint mới gắn với tài khoản nhắn tin được chỉ định. Nếu bỏ qua, endpoint thuộc workspace. Trong phản hồi, endpoint độc lập có account_id, còn endpoint workspace không có trường này.

Cấu hình riêng của tài khoảnKế thừa workspaceCần kiểm tra
Không có endpoint độc lậpCó hiệu lựcTrạng thái và đăng ký của workspace
Có endpoint active và đăng ký phù hợpDùng cấu hình tài khoản thay thếBộ nhận và cấu hình chữ ký của tài khoản
Có endpoint riêng nhưng tất cả inactiveKhông tự chuyển về workspaceCó còn cần cấu hình riêng không
Endpoint active không đăng ký sự kiện mục tiêuKhông tự chuyển về workspaceĐăng ký sự kiện của tài khoản
Đã xóa endpoint độc lập cuối cùngKhôi phục cho các lần gửi đầu tiên sau đóĐộ sẵn sàng của workspace và sự kiện thử mới

Ví dụ giả định: bộ thu của workspace đăng ký message.received, nhưng endpoint riêng của một tài khoản chỉ đăng ký account.status.updated. Đây không phải báo cáo sự cố thực tế. Đăng ký ở workspace không bù cho sự kiện tin nhắn bị bộ lọc tài khoản loại ra. Hãy sửa cấu hình tài khoản hoặc chủ động khôi phục kế thừa.

Hướng dẫn lọc sự kiện giải thích nên chọn tên sự kiện nào. Câu hỏi cần trả lời trước ở đây là: phạm vi nào chịu trách nhiệm gửi sự kiện của tài khoản này? Nếu bạn quản lý cả Zalo và WhatsApp, hãy đối chiếu theo từng tài khoản thay vì suy luận từ một tài khoản đang hoạt động.

Kiểm tra hai phạm vi bằng hai yêu cầu chỉ đọc

Dùng cùng một X-Api-Key phía máy chủ cho cả hai yêu cầu. Khóa xác định workspace. Ví dụ dưới đây chỉ minh họa đường dẫn; thay acc_example bằng ID công khai thực tế lấy từ truy vấn tài khoản:

GET /v1/webhook-endpoints
GET /v1/webhook-endpoints?account_id=acc_example

Theo tài liệu liệt kê Webhook endpoint, yêu cầu đầu chỉ trả về endpoint workspace. Yêu cầu sau chỉ trả về cấu hình độc lập của tài khoản, không kèm endpoint workspace được kế thừa. Vì vậy, data: [] trong phản hồi thành công của yêu cầu sau nghĩa là không có endpoint độc lập, không phải không có đường Webhook.

Ghi lại ID endpoint, tài khoản gắn kết, URL, status, subscribed_events, signing_enabled và chính sách thử lại. Đừng bỏ qua các mục inactive vì chúng vẫn ảnh hưởng đến kế thừa. Không đưa khóa bí mật hay nội dung tin nhắn vào hồ sơ chẩn đoán.

Tên tham số phải chính xác là account_id. Giá trị rỗng, chỉ có khoảng trắng, tham số lặp hoặc tên khác chữ hoa–thường không tương đương với việc bỏ qua tham số. Tài khoản được chỉ định không tồn tại hoặc nằm ngoài workspace sẽ trả về 404 account_not_found. Sửa ID và workspace, không xem lỗi đó là danh sách rỗng.

Nếu cả hai phạm vi đều đúng, hãy kiểm tra riêng trạng thái authorization và runtime, rồi theo dõi một sự kiện mới được hỗ trợ qua bước xác thực bộ nhận và lưu trữ bền vững. Đừng khởi động lại tài khoản đang hoạt động bình thường chỉ vì đang kiểm tra nhầm URL.

Sửa cấu hình riêng hay khôi phục kế thừa?

Giữ bộ nhận riêng cho tài khoản

Dùng cập nhật Webhook endpoint để sửa URL, trạng thái active hoặc đăng ký sự kiện của endpoint hiện tại. Giữ cấu hình chữ ký và thử lại đã được rà soát. signing_secret rỗng sẽ tắt chữ ký; không sao chép ví dụ không ký vào môi trường thật.

Nếu cùng tài khoản đã có endpoint độc lập active, việc tạo thêm một endpoint active có thể trả về 409 account_webhook_already_exists, mã số 40008. Quy tắc này cũng áp dụng khi đổi một endpoint khác từ inactive sang active. Tuy nhiên, được phép cập nhật endpoint vốn đã active và giữ active, kể cả cấu hình cũ có nhiều endpoint active. Không nên cho rằng các mục cũ sẽ được dọn tự động. Quy tắc giới hạn active này không áp dụng cho endpoint workspace.

Không thể đổi liên kết tài khoản. Khi cập nhật, account_id chỉ xác minh quyền sở hữu ban đầu; bỏ qua trường này sẽ giữ nguyên liên kết. Bỏ qua hoặc gửi null không chuyển endpoint tài khoản thành endpoint workspace, cũng không thể gán lại endpoint workspace hiện có cho một tài khoản.

Đưa tài khoản về bộ nhận của workspace

Trước tiên, xác nhận bộ nhận workspace đang active, đăng ký đúng sự kiện, và sẵn sàng kiểm tra chữ ký cũng như lưu trữ bền vững. Trao đổi tác động với người phụ trách quy trình riêng của tài khoản.

Sau đó chủ động loại bỏ cấu hình độc lập bằng xóa Webhook endpoint. Kiểm tra từng mục: để lại một endpoint inactive vẫn giữ cấu hình tài khoản. Đọc lại danh sách theo tài khoản để xác nhận không còn endpoint độc lập. Xóa thành công trả về 204 và không có body.

Đây là quyết định thay đổi định tuyến, không phải khuyến nghị bảo trì chung. Nếu chỉ cần tạm dừng CRM hoặc AI, bài so sánh các cách bảo trì Webhook giải thích vì sao tạm dừng worker phía sau có thể phù hợp hơn thay đổi endpoint.

Xác nhận đường mới mà không hứa khôi phục lịch sử

Sau khi đổi cấu hình, gửi một tin nhắn thử mới có kiểm soát. Tại bộ nhận dự kiến, xác nhận tài khoản và sự kiện, kiểm tra chữ ký theo hợp đồng gửi Webhook, lưu bền vững rồi mới xác nhận đã nhận. Kiểm tra kết quả xử lý phía sau ở bước riêng.

Đây là các bước nghiệm thu đề xuất, không phải thử nghiệm đã được thực hiện trên workspace của bạn. Nếu yêu cầu đổi cấu hình hết thời gian chờ, hãy đọc trạng thái hiện tại trước khi ghi lại. Quy tắc kế thừa áp dụng cho các lần gửi đầu tiên sau đó, không xác định hành vi của mọi yêu cầu đang xử lý.

Giao diện không chính thức của UnifyPort cung cấp luồng sự kiện chuẩn hóa, nhưng không bảo đảm phát lại payload bị bỏ lỡ. Thử nghiệm mới thành công chỉ chứng minh đường mới hoạt động, không chứng minh khoảng dữ liệu thiếu trước đó đã được khôi phục.

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

Vô hiệu hóa endpoint tài khoản có trả việc nhận sự kiện về workspace không?

Không. Cấu hình độc lập inactive vẫn được ưu tiên. Xóa endpoint độc lập cuối cùng mới khôi phục kế thừa cho các lần gửi đầu tiên sau đó.

Đổi đăng ký workspace thành wildcard có giải quyết được không?

Không giải quyết được quyền ưu tiên của cấu hình tài khoản. Hãy sửa cấu hình đang có hiệu lực hoặc chủ động xóa nó để khôi phục kế thừa.

Vì sao danh sách endpoint tài khoản rỗng?

Kết quả rỗng thành công nghĩa là không có endpoint độc lập. Đọc danh sách workspace để kiểm tra cấu hình được kế thừa. Phản hồi lỗi không phải kết quả rỗng.

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

Bắt đầu từ danh sách Webhook endpoint và đối chiếu hai phạm vi trước khi thay đổi.

Tài liệu sản phẩm chính thức được kiểm tra ngày 2026-11-15:

UnifyPort API

Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.

Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.