Hướng dẫn August 19, 2026

Bộ lọc sự kiện UnifyPort Webhook: dùng subscribed_events hay Wildcard?

Với handler production chỉ có một nhiệm vụ, hãy liệt kê rõ các sự kiện trong subscribed_events. Dùng ["*"] khi endpoint là bộ thu thập sự kiện đầy đủ hoặc khi nhóm vẫn đang xác định workflow cần gì. Wildcard bao gồm mọi sự kiện chuẩn công khai, không bao gồm raw event nội bộ. Với hộp thư hỗ trợ khách hàng qua Zalo, WhatsApp hoặc LINE, hãy bắt đầu bằng message.received và chỉ thêm sự kiện vòng đời tài khoản khi cùng một service chịu trách nhiệm theo dõi kết nối.

Điểm chính

subscribed_events nhận tên chính xác của sự kiện công khai, hoặc chỉ ["*"] để chọn toàn bộ danh mục công khai.
Tên sự kiện không tồn tại sẽ bị từ chối khi tạo hoặc cập nhật endpoint.
Subscribe một sự kiện không có nghĩa mọi provider đều phát sự kiện đó; cần kiểm tra ma trận provider.
message.received có thể mô tả tin nhắn đến hoặc đi, vì vậy phải kiểm tra data.message.direction.
Lọc sự kiện, chữ ký HMAC, xác nhận thành công và retry là các cơ chế riêng biệt.

`subscribed_events` kiểm soát điều gì

UnifyPort gửi các sự kiện được chọn trong subscribed_events đến Webhook endpoint bằng HTTP POST. Envelope chuẩn luôn có id, type, provider, account_id, occurred_at và data phụ thuộc loại sự kiện. Xem tên hợp lệ cùng cấu trúc payload trongdanh mục sự kiện chuẩn.

Cấu hình nhỏ nhất để nhận tin nhắn là:

{
  "subscribed_events": ["message.received"]
}

Handler vẫn phải lọc hướng tin nhắn:

if (
  event.type === 'message.received' &&
  event.data?.message?.direction === 'inbound'
) {
  await storeInboundMessage(event);
}

Sự kiện này cho biết một tin nhắn được quan sát trên messaging account đã kết nối. Nó không cam kết chỉ có tin nhắn đến.

Cú pháp Wildcard là:

{
  "subscribed_events": ["*"]
}

Hãy dùng nó như lựa chọn đầy đủ, không trộn "*" với các tên khác trong cùng mảng. Nó chọn mọi sự kiện chuẩn công khai nhưng không cung cấp raw event nội bộ.

Ba mẫu bộ lọc thực tế

1. Chỉ hộp thư đến

Phù hợp với service chỉ lưu và định tuyến tin nhắn của khách hàng:

{
  "subscribed_events": ["message.received"]
}

Chỉ xử lý bản ghi có data.message.direction là inbound. Khi cần theo dõi chỉnh sửa, xóa, reaction hoặc receipt, hãy thêm đúng tên sự kiện sau khi xác định cách mỗi loại cập nhật trạng thái đã lưu.

2. Hộp thư đến kèm trạng thái tài khoản

Dùng khi cùng một service cần cảnh báo hết hạn xác thực hoặc runtime mất kết nối:

{
  "subscribed_events": [
    "message.received",
    "account.status.updated",
    "account.started",
    "account.auth.required",
    "account.auth.succeeded",
    "account.auth.failed"
  ]
}

Đừng coi mọi status event là lệnh restart. Hãy ghi nhận auth_status và runtime_status, sau đó đối soát tài khoản trước khi hành động. Runbook khôi phục runtime cho messaging account giải thích khi nào cần refresh, reconnect, start hoặc xác thực lại.

3. Bộ thu thập toàn bộ sự kiện

Chọn ["*"] khi endpoint là ranh giới tiếp nhận chung và việc phân phối diễn ra ở phía sau. WhatsApp, Zalo, LINE, Telegram, TikTok và X có thể đi vào cùng một hàng đợi đã ký; các consumer riêng xử lý tin nhắn, receipt, nhóm và trạng thái tài khoản.

Bộ thu thập Wildcard vẫn cần nhánh mặc định cho sự kiện công khai được thêm trong tương lai. Lưu envelope an toàn, xác nhận delivery và chuyển type chưa hỗ trợ vào hàng đợi cách ly có giám sát. Không nên giả định mọi event đều là tin nhắn.

Tạo endpoint với bộ lọc cụ thể

Route API thật là POST /v1/webhook-endpoints. Request sau tạo endpoint đang hoạt động, có chữ ký và nhận tin nhắn cùng trạng thái tài khoản:

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"https://inbox.example.com/webhooks/unifyport\",
    \"status\": \"active\",
    \"subscribed_events\": [
      \"message.received\",
      \"account.status.updated\",
      \"account.auth.required\"
    ],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\",
    \"retry_policy\": { \"max_attempts\": 3 }
  }"

Các trường được định nghĩa trongtài liệu Create webhook endpoint. retry_policy.max_attempts đếm số lần thử lại sau delivery đầu tiên. Giá trị mặc định được ghi trong tài liệu là 3, tức một request đầu và tối đa ba lần retry. Phạm vi hợp lệ là 0 đến 5.

Để thay bộ lọc, dùng route đã được mô tả PATCH /v1/webhook-endpoints/{endpoint_id} và gửi subscribed_events mới. Quy tắc kiểm tra tên giống nhau ở cả create và update.

Tách lọc sự kiện khỏi bảo mật delivery

Bộ lọc quyết định UnifyPort gửi gì. signing_secret quyết định delivery có X-Device-Timestamp và X-Device-Signature hay không. Khi bật chữ ký, hãy xác minh HMAC-SHA256 dạng hex trên timestamp, dấu chấm và raw request body trước khi parse JSON.

Mọi phản hồi 2xx đều xác nhận delivery. Lỗi kết nối cùng HTTP 408, 429, 5xx được retry theo cấu hình; các phản hồi 4xx khác không được retry. Delivery theo nguyên tắc at-least-once, vì vậy phải xử lý các lần gửi lại sự kiện thông thường theo cách idempotent.

Xem triển khai receiver đầy đủ tronghướng dẫn Webhook delivery và xác minh chữ ký, cùngbài hướng dẫn HMAC replay protection và idempotency.

Kiểm tra provider trước khi thêm tên sự kiện

Danh mục công khai xác định tên hợp lệ, nhưng parser của các provider không map mọi sự kiện như nhau. message.received và những sự kiện tài khoản chính được hỗ trợ rộng; receipt, chỉnh sửa tin nhắn, thay đổi hội thoại và cập nhật nhóm khác nhau theo provider.

Trước khi để consumer phụ thuộc vào một sự kiện, hãy xemkhác biệt Webhook event theo provider. Subscription hợp lệ chỉ là bộ lọc, không đảm bảo tài khoản ở phía nguồn sẽ tạo event đó.

Nếu đang xây automation thay vì bộ thu thập tổng quát, bài hướng dẫn n8n WhatsApp signed webhook cho thấy vì sao xác minh và tiếp nhận bền vững nên đứng trước AI workflow.

Giới hạn và đánh đổi

Danh sách cụ thể giảm nhiễu và làm rõ trách nhiệm, nhưng phải cập nhật cấu hình khi phát sinh nhu cầu mới. Wildcard giảm nguy cơ bỏ lỡ loại công khai mới, đổi lại consumer phải tiếp nhận nhiều event hơn và chịu được phần mở rộng trong tương lai.

UnifyPort không có REST API chung để đọc lịch sử tin nhắn và không đảm bảo phát lại payload bị bỏ lỡ. Hãy đăng ký receiver trước khi kết nối messaging account production và lưu sự kiện cần thiết ngay khi chúng đến. Đồng bộ lịch sử WhatsApp có giới hạn chỉ hỗ trợ tính liên tục, không thay thế kho sự kiện của bạn.

UnifyPort cung cấp giao diện không chính thức. Nếu dự án cần quy trình chứng nhận chính thức hoặc khả năng riêng của provider nằm ngoài ma trận tài liệu, hãy dùng API chính thức của nền tảng tương ứng.

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

Nên dùng `message.received` hay `["*"]`?

Dùng message.received cho handler hộp thư chuyên biệt. Dùng ["*"] cho bộ thu thập lưu và phân phối toàn bộ sự kiện chuẩn công khai.

`message.received` chỉ có tin nhắn đến phải không?

Không. Nếu workflow chỉ xử lý tin đến, hãy kiểm tra data.message.direction là inbound.

Không. subscribed_events chỉ nhận tên chuẩn công khai và Wildcard cũng không cung cấp raw event nội bộ.

Điều gì xảy ra khi gõ sai tên sự kiện?

Request create hoặc update sẽ từ chối tên không tồn tại thay vì âm thầm lưu bộ lọc không bao giờ khớp.

`["*"]` có đảm bảo mọi event từ mọi provider không?

Không. Nó chọn tất cả loại chuẩn công khai, nhưng hỗ trợ thực tế và khả năng từ nguồn vẫn khác nhau theo provider.

Bước tiếp theo

Mởtài liệu Create webhook endpoint, chọn một trong ba mẫu trên và đăng ký receiver trước khi kết nối messaging account production.

Nguồn

Đã kiểm tra ngày 19 tháng 8 năm 2026: