Webhooks #

Webhook cho phép Your AI Connector tự động thông báo cho các công cụ kinh doanh khác của bạn bất cứ khi nào có sự kiện quan trọng xảy ra — một liên hệ mới được tạo, một cuộc hẹn được đặt, hoặc một tin nhắn được nhận. Thay vì phải kiểm tra cập nhật theo cách thủ công, các hệ thống được kết nối của bạn sẽ nhận được thông báo tức thì ngay khi có sự kiện xảy ra.

Webhooks là gì? #

Hãy coi webhook giống như một tin nhắn văn bản tự động giữa hai ứng dụng. Khi có sự kiện xảy ra trong Your AI Connector (ví dụ: một liên hệ mới đăng ký), nền tảng sẽ ngay lập tức gửi thông báo đến hệ thống khác mà bạn chọn. Bạn cung cấp một địa chỉ web (được gọi là “URL webhook”) để nhận các thông báo này — địa chỉ này thường được cung cấp bởi CRM, nền tảng tự động hóa hoặc nhà phát triển của bạn.

Webhook chỉ gửi dữ liệu RA KHỎI Your AI Connector. Webhook là một chiều từ Your AI Connector đến các công cụ khác của bạn. Không có URL webhook nào gửi khách hàng tiềm năng, liên hệ hoặc tin nhắn VÀO nền tảng. Để đẩy một khách hàng tiềm năng mới vào — từ biểu mẫu trang web, CRM hoặc GoHighLevel của bạn — hệ thống của bạn sẽ thực hiện lệnh gọi API thay thế. Xem Truy cập API (thao tác Tạo liên hệ) và Phễu. Thứ duy nhất bạn cần cho chiều dữ liệu đi vào là khóa API của bạn, nằm trong phần riêng của nó — xem Truy cập API. Trang Webhook được mô tả ở đây chỉ dành riêng cho chiều dữ liệu đi ra.

Các mục đích sử dụng phổ biến bao gồm:

• Đồng bộ hóa các liên hệ mới vào CRM của bạn.
• Kích hoạt quy trình làm việc trong Zapier, Make hoặc Pabbly khi một thẻ (tag) được áp dụng.
• Thông báo cho nhóm của bạn trên Slack khi có sự kiện cần con người can thiệp.
• Cập nhật hệ thống lịch của bạn khi một cuộc hẹn được đặt.
• Ghi lại tóm tắt cuộc trò chuyện vào cơ sở dữ liệu của bạn.

Thiết lập Webhooks #

1. Trong thanh bên trái, nhấp vào Cài đặt (biểu tượng bánh răng).
2. Trong thanh bên Cài đặt, dưới nhóm Tích hợp, nhấp vào Webhook.

Trên một tài khoản chưa được cấu hình webhook nào, trang sẽ trông như thế này:

3. Nhấp vào New webhook (Webhook mới) ở góc trên bên phải. Một biểu mẫu sẽ mở ra ngay trên trang:

4. Điền vào:
   • URL điểm cuối (Endpoint URL) — địa chỉ web mà Your AI Connector sẽ gửi thông báo sự kiện đến. Bạn lấy địa chỉ này từ hệ thống bên ngoài của mình (CRM, nền tảng tự động hóa hoặc máy chủ tùy chỉnh).
   • Tên (Name) — nhãn mà bạn sẽ nhận ra sau này (ví dụ: “Cảnh báo Slack” hoặc “Đồng bộ CRM”). Chỉ dành cho mục đích tham khảo của bạn.

URL webhook của bạn phải là một địa chỉ https:// có thể truy cập công khai. Các địa chỉ http:// thông thường, localhost hoặc địa chỉ mạng nội bộ và địa chỉ nội bộ của nền tảng sẽ bị từ chối khi bạn lưu. Để kiểm tra từ máy tính của riêng bạn, hãy sử dụng đường hầm công khai (webhook.site hoặc ngrok) thay vì localhost.

5. Trong phần Events, hãy nhấp vào các sự kiện bạn muốn webhook này nhận — tất cả 22 sự kiện được liệt kê trong The 22 Webhook Events.
6. (Tùy chọn) Bật Retry failed deliveries nếu bạn muốn Your AI Connector tiếp tục thử lại khi gặp lỗi tạm thời — xem Retrying Failed Deliveries.
7. Nhấp vào Create webhook. Webhook sẽ xuất hiện trong danh sách bên dưới biểu mẫu và bạn có thể nhấp vào Test trên hàng của nó bất kỳ lúc nào để gửi một payload mẫu đến endpoint của bạn.

Cần có quyền. Việc thêm, chỉnh sửa hoặc kiểm tra webhook yêu cầu quyền “chỉnh sửa” Tích hợp (thành viên nhóm chỉ có quyền xem sẽ thấy thông báo chỉ đọc thay vì biểu mẫu).

Việc ký webhook yêu cầu nó phải được lưu trước — hãy mở hàng của webhook hiện có để chỉnh sửa, và bảng Bí mật ký (Signing secret) sẽ xuất hiện ở cuối biểu mẫu chỉnh sửa. Một bản nháp mới hoàn toàn chưa được lưu sẽ chưa có tùy chọn ký — xem Payload đã ký bên dưới.

Một Webhook cho tất cả tài khoản khách hàng của bạn (Dành cho đại lý) #

Nếu bạn điều hành một đại lý, bạn không cần phải tạo lại cùng một webhook trên mỗi tài khoản khách hàng. Trên tài khoản đại lý, biểu mẫu webhook có thêm một nút chuyển đổi: Cũng kích hoạt cho tất cả tài khoản khách hàng. Hãy bật nó lên và webhook này cũng sẽ nhận các sự kiện xảy ra trên mọi tài khoản khách hàng thuộc đại lý của bạn — một điểm cuối, toàn bộ đại lý.

Cách thức hoạt động:

• Khối user cho bạn biết sự kiện thuộc về khách hàng nào. Mọi thông báo đều đã chứa một khối user xác định tài khoản nơi sự kiện xảy ra, vì vậy hệ thống tự động hóa của bạn có thể định tuyến theo từng khách hàng.
• Các cài đặt riêng của webhook được áp dụng ở mọi nơi. Các sự kiện bạn đã chọn, bí mật ký và cài đặt thử lại cũng được sử dụng cho việc gửi đến tài khoản khách hàng.
• Không gửi trùng lặp. Nếu một tài khoản khách hàng có webhook riêng trỏ đến cùng một URL, webhook đó sẽ được sử dụng cho các sự kiện của tài khoản đó thay vì webhook của đại lý — cùng một sự kiện sẽ không bao giờ đến cùng một điểm cuối hai lần.
• Khách hàng không nhìn thấy webhook này. Webhook không xuất hiện trên trang Webhooks của chính tài khoản khách hàng và khách hàng không thể tắt nó — bạn là người quản lý nó.
• Độ tin cậy được theo dõi theo từng tài khoản khách hàng. Nếu điểm cuối của bạn liên tục thất bại, nó sẽ tự động bị tắt đối với tài khoản có các lần gửi thất bại (xem Độ tin cậy của Webhook), chứ không phải tắt cho toàn bộ đại lý cùng một lúc.

Nút chuyển đổi này chỉ xuất hiện trên các tài khoản đại lý. Việc thiết lập thông qua API cũng được hỗ trợ — xem trường apply_to_sub_accounts trong API Webhooks.

Các sự kiện kích hoạt khả dụng #

Bạn có thể bật hoặc tắt độc lập từng sự kiện trong số 22 sự kiện webhook. Khi một sự kiện được kích hoạt, Your AI Connector sẽ gửi thông báo đến URL webhook của bạn kèm theo dữ liệu liên quan. Mọi sự kiện, ý nghĩa của chúng và mã event mà chúng đưa vào payload đều được liệt kê cùng nhau trong The 22 Webhook Events ở phần dưới của trang này.

Cần lưu ý: Task Created, Task Updated và Task Completed có thể chọn đầy đủ và lưu chính xác. Daily Summary Created cũng là một bổ sung gần đây. Xem Webhook Task Completed bên dưới để biết cấu trúc payload đó.

Các trình kích hoạt Webhook dựa trên thẻ #

subscribed_to_tags không giới hạn phạm vi các sự kiện của webhook theo thẻ. Nó chỉ thu hẹp những thẻ nào sẽ tạo ra thông báo tóm tắt cuộc trò chuyện. Để nhận yêu cầu khi một thẻ cụ thể được áp dụng, hãy đặt URL webhook trên thẻ đó trong tab Tags của tác nhân (hoặc chiến dịch).

Bản thân biểu mẫu webhook không có bộ chọn thẻ, dù là khi tạo webhook mới hay khi chỉnh sửa, vì vậy subscribed_to_tags chỉ có thể được đọc hoặc thay đổi thông qua Webhooks API, hoặc bằng cách yêu cầu bộ phận hỗ trợ.

Cần lưu ý: việc chỉnh sửa một webhook hiện có có danh sách subscribed_to_tags (đổi tên, thay đổi sự kiện, bật/tắt thử lại) sẽ không còn xóa danh sách đó nữa — vì biểu mẫu không có bộ chọn thẻ để gửi lại, nên việc lưu từ trang này hiện sẽ giữ nguyên danh sách hiện có. (Đây là một lỗi thực sự trước ngày 21 tháng 7 năm 2026: việc lưu từ biểu mẫu webhook trước đây thường xóa danh sách vì nó luôn gửi một danh sách thẻ trống. Nếu webhook bị mất danh sách subscribed_to_tags trước ngày đó, nó sẽ cần được cấu hình lại thông qua API.)

Tạo tóm tắt cho các liên hệ được gắn thẻ #

Khi webhook có danh sách subscribed_to_tags, bạn có thể bật Generate Summary. Khi được bật, Your AI Connector sẽ tự động tạo tóm tắt cuộc trò chuyện cho liên hệ khi một trong những thẻ đó được áp dụng và đưa nó vào dữ liệu webhook — cung cấp ngữ cảnh đầy đủ mà không cần yêu cầu riêng biệt.

Kiểm tra Webhook của bạn #

1. Mở Cài đặt → Tích hợp → Webhooks.
2. Trên hàng webhook của bạn, nhấp vào Kiểm tra.
3. Kiểm tra hệ thống bên ngoài của bạn để xác nhận rằng nó đã nhận được dữ liệu kiểm tra.
4. Xem lại định dạng dữ liệu để đảm bảo hệ thống của bạn có thể phân tích cú pháp nó một cách chính xác.

Để kiểm tra toàn diện từ đầu đến cuối, hãy gửi một tin nhắn có thể kích hoạt một trong các sự kiện đã định cấu hình của bạn (một chương trình phát sóng hoặc một tin nhắn đến trên kênh được kết nối) và xác minh rằng webhook kích hoạt với dữ liệu thực.

Điều gì được coi là gửi thành công #

Cho dù bạn nhấp vào Test hay sự kiện thực sự được kích hoạt, chúng tôi đều gửi cùng một nội dung:

• Một yêu cầu POST (không bao giờ là GET), với phần thân là JSON và Content-Type: application/json.
• Các tiêu đề được liệt kê trong phần Signed Payloads. Các tiêu đề chữ ký chỉ được bao gồm sau khi bạn đã thiết lập bí mật ký.

Chúng tôi coi việc gửi là thành công khi:

• Điểm cuối của bạn phản hồi bằng bất kỳ trạng thái 2xx nào (200, 201, 204 — tất cả đều ổn).
• Phản hồi trong vòng 30 giây.

Một vài điều khiến mọi người ngạc nhiên:

• Phần thân phản hồi (response body) sẽ bị bỏ qua. Bạn không cần trả về bất kỳ JSON cụ thể nào. Một phản hồi 200 trống là đủ.
• Chuyển hướng (redirects) được tính là thất bại. Chúng tôi không theo dõi các chuyển hướng, vì vậy mã 301 hoặc 302 (bao gồm cả chuyển hướng dấu gạch chéo ở cuối, hoặc http sang https) sẽ được ghi nhận là gửi thất bại. Hãy lưu URL cuối cùng, không phải URL chuyển hướng.
• Chuỗi truy vấn (query strings) được hỗ trợ đầy đủ. https://your-app.com/hook?token=abc123 được gửi chính xác như cách bạn đã lưu, vì vậy việc đặt mã thông báo (token) vào chuỗi truy vấn cũng hiệu quả như đặt nó vào đường dẫn.
• URL của bạn phải là https:// và có thể truy cập công khai. Các địa chỉ thuộc cơ sở hạ tầng của chính Your AI Connector sẽ bị từ chối, nhưng các điểm cuối (endpoint) của riêng bạn trên Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting hoặc bất kỳ nơi nào khác đều ổn.
• Tường lửa hoặc lớp bảo vệ bot phía trước điểm cuối của bạn có thể chặn chúng tôi. Trường hợp phổ biến nhất là Cloudflare: nếu vùng (zone) của bạn đã bật Bot Fight Mode hoặc có thử thách được quản lý, yêu cầu của chúng tôi sẽ nhận được trang thử thách “Just a moment…” với mã 403 thay vì đến được máy chủ của bạn — và một yêu cầu máy chủ-đến-máy chủ không bao giờ có thể vượt qua thử thách trình duyệt, vì vậy cả nút Kiểm tra (Test) và các sự kiện thực tế đều thất bại theo cùng một cách. Nút Kiểm tra sẽ thông báo cho bạn khi điều này xảy ra (“Cloudflare đang hiển thị thử thách bot cho yêu cầu của chúng tôi”). Hãy khắc phục trong Cloudflare bằng quy tắc Bảo mật / WAF để bỏ qua các thử thách cho đường dẫn webhook của bạn (hoặc cho tác nhân người dùng Webhook-Delivery/1.0), sau đó nhấp vào Kiểm tra (Test) một lần nữa.
• Nếu tường lửa của bạn cần danh sách IP cho phép (IP allowlist) thay thế (ví dụ: gói miễn phí của Cloudflare, nơi Bot Fight Mode thông thường không thể bị bỏ qua bởi quy tắc WAF, nhưng Quy tắc Truy cập IP được đặt thành Cho phép sẽ chạy trước nó), chúng tôi có thể trợ giúp: mọi lần gửi, dù từ nút Kiểm tra (Test) hay sự kiện trực tiếp, đều được gửi từ một địa chỉ IPv4 cố định (không có dải IP, không có IPv6, không xoay vòng). Hãy liên hệ với bộ phận hỗ trợ và chúng tôi sẽ cung cấp địa chỉ để bạn đưa vào danh sách cho phép. Hãy giữ xác minh chữ ký làm bước kiểm tra độ tin cậy thực tế của bạn, vì nó xác thực mọi payload bất kể nó đến từ đâu.
• Kết quả Kiểm tra cho bạn biết chính xác điểm cuối của bạn đã trả lời như thế nào. Một bài kiểm tra thất bại hiện hiển thị lý do thực tế (trạng thái HTTP mà điểm cuối của bạn đã trả về, thời gian chờ, hoặc việc chúng tôi không thể truy cập địa chỉ đó) thay vì một lỗi chung chung, và một bài kiểm tra trên webhook đã lưu sẽ được gửi kèm chữ ký khi tính năng ký được bật, giống hệt như một sự kiện trực tiếp.

Sử dụng n8n, Make hoặc Zapier (“Test URL” so với “Production URL”) #

Các nền tảng tự động hóa thường cung cấp cho bạn hai địa chỉ webhook khác nhau, và điều này thường gây nhầm lẫn cho người dùng:

• Một URL kiểm tra (trong n8n nó chứa /webhook-test/). URL này chỉ nhận dữ liệu khi bạn đang tích cực theo dõi canvas và vừa nhấp vào Nghe sự kiện kiểm tra (hoặc Kiểm tra quy trình làm việc). Nó nắm bắt một sự kiện duy nhất rồi ngừng lắng nghe — vì vậy việc nhấp vào Kiểm tra trong Your AI Connector nhiều lần liên tiếp chỉ bắt được sự kiện đầu tiên, và chỉ khi cửa sổ lắng nghe đang hoạt động tại thời điểm đó. Để kiểm tra: trước tiên hãy nhấp vào Nghe sự kiện kiểm tra trong n8n, sau đó quay lại Your AI Connector và nhấp vào Kiểm tra một lần.
• Một URL sản xuất (trong n8n nó chứa /webhook/, không có -test). Đây là URL để dán vào Your AI Connector cho các sự kiện trực tiếp. Nó chỉ hoạt động khi quy trình làm việc của bạn được chuyển sang Đang hoạt động. Nếu quy trình làm việc không hoạt động, n8n sẽ từ chối yêu cầu với lỗi “404 / webhook không được đăng ký”, mặc dù Your AI Connector đã gửi dữ liệu chính xác.

Tóm lại: hãy kiểm thử với URL Kiểm thử trong khi đang lắng nghe, nhưng để webhook tiếp tục hoạt động với các liên hệ thực tế, hãy lưu URL Sản xuất vào Your AI Connector và đảm bảo quy trình làm việc đang ở trạng thái Active.

Định dạng dữ liệu Webhook #

Khi một webhook được kích hoạt, Your AI Connector sẽ gửi dữ liệu có cấu trúc (JSON) đến URL webhook của bạn. Nếu bạn đang sử dụng nền tảng tự động hóa như Zapier hoặc Make, nó sẽ tự động phân tích dữ liệu này cho bạn. Nếu bạn đang xây dựng một tích hợp tùy chỉnh:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign hoặc agent — thường là một trong hai, không phải cả hai. Nếu tài khoản của bạn sử dụng nhân viên, các liên hệ của bạn sẽ nằm với nhân viên thay vì chiến dịch, vì vậy campaign sẽ hiển thị dưới dạng null và agent cho bạn biết ai là người đã xử lý nó. Các tài khoản dựa trên chiến dịch cũ hơn sẽ thấy ngược lại. Hãy đọc phần nào được điền thông tin; đừng giả định rằng campaign luôn luôn có ở đó.

Khối agent đã được ra mắt vào ngày 15 tháng 8 năm 2026. Nó nằm cùng với campaign trong các sự kiện gắn liền với một cuộc hội thoại — một cuộc trò chuyện đã kết thúc, chế độ không làm phiền, tiếp tục, bỏ lưu trữ, tạm dừng AI, tin nhắn mới, tóm tắt cuộc hội thoại và webhook bạn có thể thiết lập trên một thẻ — và mang theo id và name của tác nhân xử lý, hoặc null khi không có tác nhân nào tham gia. Đây hoàn toàn là phần bổ sung: mọi trường bạn đã nhận được đều không thay đổi, vì vậy trình nhận mà bạn đã xây dựng trước ngày đó vẫn tiếp tục hoạt động mà không cần cập nhật gì cả.

Một số sự kiện bổ sung khối cấp cao nhất của riêng chúng. Ví dụ: Appointment Booked (Đã đặt lịch hẹn) thêm một khối appointment (xem Webhook Đã đặt lịch hẹn), New Message (Tin nhắn mới) thêm một khối message đầy đủ kèm theo văn bản (xem Webhook Tin nhắn mới), và Deliveries (Đã gửi) cùng Reads (Đã đọc) thêm một khối message ngắn chỉ chứa ID và trạng thái của tin nhắn (xem Webhook Đã gửi và Đã đọc).

Deliveries và Reads cho bạn biết tin nhắn nào, nhưng không cho biết nội dung tin nhắn đó. Chúng mang theo một khối message chứa id và status của tin nhắn — và id đó chính là messageId mà điểm cuối gửi tin nhắn trả về, vì vậy bạn có thể khớp biên nhận đã gửi hoặc đã đọc với chính xác tin nhắn bạn đã gửi — nhưng không có nội dung tin nhắn. Replies (Phản hồi) không mang theo khối message nào cả. Nếu bạn cần nội dung văn bản đã gửi hoặc nhận, hãy đăng ký New Message cùng với chúng.

Hai điều cần biết trước khi bạn viết trình nhận. Không có trường timestamp và không có trình bao bọc data. Mọi khối đều nằm ở cấp cao nhất của đối tượng JSON, như hiển thị ở trên.

The 22 Webhook Events #

22 sự kiện webhook, với nhãn hiển thị mà bạn đánh dấu trong ứng dụng và mã event được gửi trong payload. Mã event là một chuỗi ngắn không khớp với nhãn hiển thị, vì vậy hãy khớp bộ nhận của bạn dựa trên mã, không phải nhãn:

Hai mã nữa không bao giờ xuất hiện trong danh sách đó vì bạn không đăng ký chúng: contact_tags_updated, được gửi bởi URL webhook đặt trên một thẻ riêng lẻ và summary_generated, được gửi khi tóm tắt cuộc trò chuyện được viết cho một thẻ trong danh sách subscribed_to_tags của webhook.

Kênh đã kết nối hiện chưa được gửi. Nó xuất hiện trong danh sách sự kiện, nhưng hiện tại không có gì kích hoạt nó. Đừng xây dựng dựa trên nó.

Các thông báo dựa trên thẻ và tác vụ sử dụng các hình thức riêng biệt. Xem Cập nhật thẻ liên hệ và Tác vụ đã hoàn thành.

Webhook Liên hệ được tạo (Contact Created) #

Được gửi khi sự kiện Liên hệ được tạo kích hoạt (một liên hệ mới được thêm thủ công, thông qua nhập dữ liệu hoặc thông qua API).

Tên sự kiện #

contactCreated

Định dạng dữ liệu (Payload) #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Mẫu “Kiểm tra” và một sự kiện thực tế trông hơi khác nhau. Nút kiểm tra gửi dữ liệu giữ chỗ (John Doe, một chiến dịch mẫu). Một sự kiện Liên hệ được tạo thực tế mang thông tin chi tiết của liên hệ thực, và một số trường có thể trống tùy thuộc vào kênh.

New Message Webhook #

Webhook này kích hoạt mỗi khi một tin nhắn được thêm vào cuộc hội thoại, trên bất kỳ kênh nào. Nó bao gồm cả hai chiều: tin nhắn liên hệ gửi cho bạn và tin nhắn AI, nhóm của bạn hoặc chiến dịch gửi cho họ. Đây là webhook duy nhất bao gồm văn bản tin nhắn, vì vậy đây là webhook cần sử dụng khi bạn muốn đồng bộ các cuộc hội thoại vào một hệ thống bên ngoài.

Tên sự kiện #

new_message

Định dạng dữ liệu (Payload) #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Vẫn không có khối campaign trong payload này. New Message gửi contact, agent, user và message. Khối agent đã được thêm vào ngày 15 tháng 8 năm 2026 và cho bạn biết tác nhân nào xử lý cuộc hội thoại; nếu bạn cũng cần ngữ cảnh chiến dịch, hãy tra cứu liên hệ thông qua API bằng cách sử dụng contact.id.

Các bản ghi AI nội bộ không kích hoạt webhook này. Bên cạnh các tin nhắn thực, nền tảng lưu giữ các hàng ghi chép riêng của nó trong một cuộc hội thoại (các lệnh gọi công cụ của AI và các bản ghi lượt hội thoại nội bộ). Những dữ liệu đó không bao giờ được gửi — bạn chỉ nhận được các tin nhắn thực sự được gửi hoặc nhận.

Webhook Đã gửi và Đã đọc #

Hai sự kiện này báo cáo những gì đã xảy ra với tin nhắn sau khi nó rời khỏi Your AI Connector: Deliveries kích hoạt khi tin nhắn đến được liên hệ (hoặc gửi thất bại), và Reads kích hoạt khi liên hệ mở tin nhắn đó, trên các kênh hỗ trợ biên nhận đã đọc.

Cả hai đều mang theo một khối message với ID của tin nhắn liên quan đến sự kiện, vì vậy bạn có thể khớp bản cập nhật với chính xác tin nhắn bạn đã gửi.

Tên sự kiện #

delivered và undelivered cho Deliveries, read cho Reads.

Định dạng dữ liệu (Payload) #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Cách khớp bản cập nhật với tin nhắn bạn đã gửi. Lưu trữ messageId bạn nhận được khi gửi tin nhắn qua API. Khi thông báo Deliveries hoặc Reads đến, hãy tra cứu ID đã lưu đó với message.id trong payload — đó chính là biên nhận đã gửi hoặc đã đọc cho chính xác tin nhắn đó.

Không có văn bản tin nhắn ở đây. Khối message chỉ chứa ID và trạng thái. Hãy đăng ký New Message nếu bạn cũng cần nội dung tin nhắn.

Khối message chỉ xuất hiện khi chúng tôi biết đó là tin nhắn nào. Trong trường hợp hiếm hoi không thể liên kết bản cập nhật với tin nhắn đã lưu, khối này sẽ bị bỏ qua hoàn toàn thay vì gửi trống — vì vậy hãy kiểm tra xem message có tồn tại trước khi đọc message.id.

Một thông báo cho mỗi lần thay đổi trạng thái. Một tin nhắn đi thông thường tạo ra một thông báo delivered và sau đó, trên các kênh có biên nhận đã đọc, một thông báo read. Gửi thất bại sẽ tạo ra undelivered thay thế.

Webhook Đặt lịch hẹn #

Kích hoạt khi một liên hệ đặt lịch hẹn. Nó kích hoạt theo cùng một cách cho dù AI đã đặt lịch trong cuộc trò chuyện, bạn tự đặt lịch hay lịch được đặt thông qua API.

Tên sự kiện #

booked

Định dạng dữ liệu (Payload) #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id thường là null trong webhook này, và điều đó là bình thường. Sự kiện Google Calendar được tạo cùng lúc với thông báo này, vì vậy ID thường chưa sẵn sàng. Hãy tìm nạp lại cuộc hẹn theo appointment_id của nó một lát sau nếu bạn cần. Nó sẽ giữ nguyên là null vĩnh viễn nếu tài khoản không có Google Calendar được kết nối, vì vậy đừng chờ đợi nó mãi.

Nút “Kiểm tra” không bao gồm khối appointment. Hãy sử dụng nó để xác nhận điểm cuối của bạn phản hồi, sau đó thực hiện một lượt đặt lịch thực tế để xem toàn bộ tải trọng.

Hai trường hợp webhook này không kích hoạt: các cuộc hẹn được nhập từ lịch bên ngoài và các lượt đặt chỗ đến thông qua tích hợp Formitable.

Webhook Cập nhật Thẻ Liên hệ #

Kích hoạt khi một thẻ được áp dụng cho một liên hệ, và thẻ đó đã được cấu hình URL webhook trên tác nhân hoặc chiến dịch mà liên hệ đó thuộc về.

Tên sự kiện #

contact_tags_updated

Khi nào sự kiện được kích hoạt #

• Một thẻ được áp dụng cho một liên hệ đã được chỉ định tác nhân, chiến dịch, hoặc cả hai.
• Ít nhất một trong các thẻ được áp dụng có URL webhook được thiết lập trong tab Thẻ (Tags) của tác nhân hoặc chiến dịch đó.

Nếu liên hệ có cả hai và các thẻ của chiến dịch có chứa URL webhook, thì các thẻ đó sẽ được ưu tiên; nếu không, các thẻ của tác nhân sẽ được sử dụng.

Nếu nhiều thẻ với các URL webhook khác nhau được áp dụng trong cùng một bản cập nhật, một yêu cầu sẽ được gửi cho mỗi URL, mỗi yêu cầu chỉ chứa các thẻ ánh xạ tới URL đó.

Việc xóa thẻ sẽ không bao giờ gửi yêu cầu. Hầu hết mọi người trỏ các URL này tới một hành động — thu tiền đặt cọc, đặt lịch, thông báo cho đại diện — vì vậy việc một thẻ bị xóa khỏi liên hệ trước đây thường kích hoạt lại hành động đó. Hiện tại điều này không còn xảy ra nữa. Việc xóa thẻ vẫn hiển thị trong removed_tags khi nó xảy ra trong cùng một bản cập nhật với việc áp dụng thẻ đi cùng một URL, vì vậy một quy trình tự động đọc cả hai mảng sẽ giữ được bức tranh toàn cảnh; điều mà nó sẽ không bao giờ thấy là một yêu cầu chỉ do việc xóa thẻ gây ra. (Đã thay đổi vào ngày 12 tháng 8 năm 2026. Trước ngày đó, việc xóa thẻ cũng gửi một yêu cầu.)

Định dạng dữ liệu (Payload) #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Kiểm tra webhook thẻ #

Bên cạnh trường URL webhook trên tab Thẻ (Tags) có một nút Kiểm tra (Test). Nút này sẽ gửi ngay một payload mẫu đến URL đó để bạn có thể xác nhận tự động hóa của mình nhận được nó trước khi chờ đợi một cuộc hội thoại thực tế.

Bài kiểm tra gửi cùng một hình dạng contact_tags_updated như hiển thị ở trên, sử dụng một liên hệ giữ chỗ, với thẻ bạn đang kiểm tra trong added_tags và một removed_tags trống. Những gì tự động hóa của bạn thấy trong bài kiểm tra chính là những gì nó sẽ thấy trong môi trường thực tế.

Hai điều cần biết:

• Lưu thẻ trước. Bài kiểm tra sẽ tìm thẻ theo tên đã lưu của nó, vì vậy một thẻ hoàn toàn mới hoặc thẻ vừa đổi tên chưa được lưu sẽ không thể kiểm tra được. Nút này vẫn bị xám cho đến khi tên trên màn hình khớp với tên đã lưu.
• Một bài kiểm tra thất bại không tính vào webhook của bạn. Các bài kiểm tra không bao giờ góp phần vào việc tự động tắt sau các lần thất bại liên tiếp được mô tả trong Độ tin cậy của Webhook.

Nếu bài kiểm tra thất bại, thông báo sẽ cho bạn biết điểm cuối của bạn đã phản hồi gì (ví dụ: 404 hoặc 500), điều này thường đủ để phát hiện URL sai hoặc quy trình làm việc chưa được bật.

Webhook Hoàn thành Tác vụ #

Chỉ dành cho mục đích tham khảo. Webhook tác vụ (dưới dạng dữ liệu) được ghi lại ở đây cho các nhà phát triển; các sự kiện Task Created, Task Updated và Task Completed có thể chọn trong danh sách sự kiện tiêu chuẩn trên biểu mẫu webhook giống như bất kỳ sự kiện nào khác — xem Available Trigger Events và The 22 Webhook Events.

Payload này được gửi khi một tác vụ chuyển sang giai đoạn được đánh dấu là giai đoạn hoàn thành. Một tác vụ di chuyển giữa các giai đoạn không phải hoàn thành sẽ gửi hình dạng taskUpdated thay thế.

Tên sự kiện #

taskCompleted

Khi nào sự kiện được kích hoạt #

• Một tác vụ được cập nhật.
• Giá trị stage của nó thay đổi so với giá trị trước đó.
• Giai đoạn mới được cấu hình là giai đoạn hoàn thành trong cài đặt giai đoạn tác vụ của tài khoản.

Định dạng dữ liệu (Payload) #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Tắt (hoặc Xóa) Webhook #

Mỗi webhook đều có một công tắc bật/tắt ngay trên hàng của nó. Tắt một webhook sẽ khiến nó ngừng nhận sự kiện, nhưng vẫn giữ nguyên mọi thứ bạn đã cấu hình — URL, các sự kiện, bất kỳ khóa bí mật ký nào. Bật lại và nó sẽ tiếp tục từ nơi nó dừng lại; không có gì xảy ra trong khi nó bị tắt được gửi sau đó.

Hãy sử dụng tính năng này khi bạn muốn tạm dừng việc gửi dữ liệu: điểm cuối (endpoint) của bạn đang được xây dựng lại, bạn đang gỡ lỗi một tích hợp gây nhiễu hoặc bạn đang tạm dừng một quy trình tự động hóa.

Xóa một webhook (biểu tượng thùng rác trên hàng của nó) sẽ xóa nó vĩnh viễn, bao gồm cả khóa bí mật ký của nó. Nếu bạn chỉ muốn dừng việc gửi, hãy tắt nó thay vì xóa — xóa là dành cho khi bạn đã hoàn toàn xong việc với điểm cuối đó.

Điều này không giống với việc webhook bị tắt tự động. Nếu chúng tôi vô hiệu hóa webhook của bạn sau nhiều lần thất bại (xem Độ tin cậy của Webhook), nút chuyển đổi ở trên sẽ không kích hoạt lại nó. Sau khi điểm cuối của bạn đã được sửa, hãy chỉnh sửa webhook và lưu lại với URL đã thay đổi (bất kỳ thay đổi URL nào cũng sẽ kích hoạt lại nó), hoặc gọi điểm cuối kích hoạt lại thông qua API — hoặc liên hệ với bộ phận hỗ trợ và chúng tôi sẽ bật lại cho bạn.

Payload đã ký (Xác minh Webhook thực sự đến từ chúng tôi) #

Bất kỳ ai biết URL webhook của bạn đều có thể gửi một yêu cầu giả mạo đến đó. Nếu bạn thực hiện các hành động tự động dựa trên webhook — cập nhật thanh toán, tạo bản ghi CRM — việc bật ký (signing) cho phép bạn xác minh từng yêu cầu thực sự đến từ chúng tôi.

Việc ký là tùy chọn và mặc định bị tắt, và bạn bật nó cho từng webhook từ chế độ xem chỉnh sửa của webhook đó (mở hàng của một webhook đã lưu).

Bật tính năng ký #

1. Mở webhook (Cài đặt → Tích hợp → Webhooks → nhấp vào hàng webhook của bạn).
2. Trong phần Khóa bí mật ký (Signing secret), nhấp vào Tạo (Generate).
3. Sao chép khóa bí mật (nó bắt đầu bằng whsec_) và lưu trữ nó trong hệ thống nhận của bạn. Hãy coi nó như một mật khẩu.

Bạn có thể quay lại và hiển thị, sao chép, xoay vòng hoặc tắt khóa bí mật bất cứ lúc nào từ cùng bảng điều khiển này.

Những gì chúng tôi gửi #

Khi tính năng ký đã được bật, mọi lần gửi cho webhook đó sẽ mang theo hai tiêu đề HTTP bổ sung sau:

Ba tiêu đề này có trong mọi lần gửi, dù có ký hay không:

Cách xác minh #

Chữ ký là HMAC-SHA256 của chuỗi <timestamp>.<raw request body>, sử dụng mã bí mật ký của bạn làm khóa.

Xác minh dựa trên nội dung yêu cầu thô — chính xác các byte bạn đã nhận được. Nếu framework của bạn phân tích cú pháp JSON và tuần tự hóa lại nó trước khi kiểm tra, các byte có thể thay đổi và chữ ký sẽ không khớp.

Ví dụ cho Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Ví dụ cho Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

So sánh các chữ ký bằng hàm an toàn với thời gian (timing-safe function) (timingSafeEqual / compare_digest), không phải ==. Việc này không tốn phí và giúp tránh được một loại tấn công tinh vi.

Xoay vòng secret #

Nhấp vào Xoay vòng (Rotate) để thay thế bí mật. Việc chuyển đổi diễn ra ngay lập tức: lần gửi tiếp theo sẽ chỉ được ký bằng bí mật mới. Nếu endpoint của bạn đang hoạt động, hãy chấp nhận cả bí mật cũ và mới trong vài phút trong khi bạn triển khai bí mật mới.

Việc tắt tính năng ký chỉ đơn giản là ngừng gửi các tiêu đề chữ ký.

Thử lại các lần gửi thất bại #

Theo mặc định, một lần gửi thất bại sẽ không được thử lại — nếu hệ thống của bạn ngừng hoạt động vào thời điểm đó, sự kiện đó sẽ bị bỏ lỡ.

Bật Thử lại các lần gửi thất bại (Retry failed deliveries) trên webhook (trong biểu mẫu tạo/chỉnh sửa) và chúng tôi sẽ tiếp tục thử lại:

Khoảng thời gian đó kéo dài khoảng 2 giờ 40 phút, vì vậy webhook có thể vượt qua cửa sổ bảo trì hoặc sự cố ngắn hạn từ phía bạn.

Những gì được thử lại: các vấn đề tạm thời — máy chủ của bạn trả về lỗi 5xx, hết thời gian chờ (timeout) hoặc lỗi kết nối.

Điều gì không được thử lại: nếu endpoint của bạn tự từ chối yêu cầu (bất kỳ mã 4xx nào), chúng tôi sẽ không thử lại — việc gửi lại cùng một yêu cầu đó cũng chỉ tạo ra kết quả từ chối tương tự.

Những sự kiện nào sẽ thử lại: webhook thẻ (contact_tags_updated), ba sự kiện tác vụ và tóm tắt hàng ngày. Các sự kiện còn lại chỉ được gửi một lần, vì vậy đối với những sự kiện đó, công tắc không có tác dụng gì. Mọi sự kiện vẫn mang theo X-Webhook-Delivery, vì vậy một quy tắc khử trùng lặp duy nhất bao gồm tất cả chúng.

Chỉ bật tính năng thử lại nếu endpoint của bạn có tính lũy đẳng (idempotent). Thử lại nghĩa là cùng một sự kiện có thể đến nhiều lần. Hãy sử dụng tiêu đề X-Webhook-Delivery để nhận diện sự kiện lặp lại: tiêu đề này giữ nguyên trong mọi lần thử cho một sự kiện, vì vậy bạn có thể bỏ qua ID mà bạn đã xử lý một cách an toàn.

Các lần thử lại tương tác với cơ chế tự động tắt sau khi thất bại liên tục (xem Độ tin cậy của Webhook) theo cách bạn mong muốn: bộ đếm lỗi sẽ tính toàn bộ quá trình gửi, chỉ sau khi tất cả các lần thử lại đã được sử dụng hết — chứ không phải từng lần thử riêng lẻ.

Độ tin cậy của Webhook #

• Your AI Connector gửi webhook qua kết nối bảo mật (HTTPS). Hãy đảm bảo địa chỉ web bạn cung cấp sử dụng HTTPS.
• Nếu hệ thống của bạn trả về lỗi, việc gửi sẽ được coi là thất bại.
• Theo dõi thời gian hoạt động của hệ thống nhận để tránh bỏ lỡ các sự kiện.
• Đối với các quy trình làm việc quan trọng, hãy bật Thử lại các lần gửi thất bại và cân nhắc thêm cơ chế dự phòng.

Webhook sẽ tự động bị tắt sau nhiều lần thất bại. Nếu URL webhook của bạn liên tục gặp lỗi (khoảng 5 lỗi liên tiếp, hoặc 3 lỗi liên tiếp đối với các lỗi kiểu cấu hình), Your AI Connector sẽ tự động ngừng gửi sự kiện đến URL đó. Để kích hoạt lại sau khi điểm cuối của bạn đã hoạt động bình thường: hãy chỉnh sửa webhook và lưu lại với URL đã thay đổi (bất kỳ thay đổi URL nào cũng sẽ kích hoạt lại nó), hoặc sử dụng điểm cuối kích hoạt lại thông qua API — việc lưu lại với cùng một URL là không đủ. Bộ phận hỗ trợ cũng có thể kích hoạt lại nó giúp bạn.

Khắc phục sự cố #

Các bước tiếp theo #

• Tích hợp GoHighLevel — sử dụng webhook để tích hợp Your AI Connector với GHL.
• Truy cập API — kết hợp webhook với API để tạo các tự động hóa mạnh mẽ.
• Sử dụng thẻ để gắn nhãn liên hệ — thiết lập các thẻ kích hoạt webhook của bạn.