> For the complete documentation index, see [llms.txt](https://docs.abot.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abot.vn/rest-api-and-webhooks/huong-dan-cau-hinh-webhooks.md).

# Hướng dẫn Cấu hình Webhooks

**Webhook** là cơ chế thông báo theo thời gian thực (Real-time). Bất cứ khi nào có sự kiện xảy ra trên ABOT (ví dụ: Khách hàng điền Form, Mở Email, Nhấp vào liên kết, Được cộng điểm hoặc Thay đổi Phân khúc), ABOT sẽ tự động gửi một gói tin HTTP POST chứa toàn bộ dữ liệu liên quan sang hệ thống đích của bạn (Lark Base, Google Sheets, CRM, ERP, Telegram Bot hoặc các workflow n8n/Make).

***

## 1. Các bước tạo Webhook trong ABOT

1. Đăng nhập vào trang quản trị ABOT.
2. Bấm vào biểu tượng **Bánh răng (Cài đặt)** ở góc trên bên phải ➡️ Chọn **Webhooks**.
3. Bấm nút **New (Tạo mới)** ở góc trên bên phải.
4. Điền các thông tin cơ bản:
   * **Name (Tên Webhook):** Đặt tên mô tả (ví dụ: `Đồng bộ Contact mới sang Lark Base` hoặc `Thông báo khách mở email VIP`).
   * **Webhook POST Url:** Điền URL nhận dữ liệu của hệ thống đích (ví dụ URL Webhook của n8n, Make hoặc server của bạn).
   * **Secret:** (Tùy chọn) Khóa bí mật dùng để mã hóa chữ ký HMAC, giúp xác thực gói tin gửi từ ABOT.
   * **Events to send (Sự kiện cần gửi):** Chọn thời điểm gửi:
     * *Send immediately (Gửi ngay lập tức khi phát sinh sự kiện - Khuyên dùng).*
     * *Send via queue (Gửi qua hàng đợi xử lý định kỳ).*
5. Chọn tab **Webhook Events (Các sự kiện Webhook)**:
   * Tích chọn một hoặc nhiều sự kiện bạn muốn lắng nghe (xem danh sách bên dưới).
6. Bấm **Apply** hoặc **Save & Close**.

***

## 2. Các sự kiện Webhook phổ biến trong ABOT

* **Contact Events (Sự kiện Liên hệ):**
  * `Contact Created`: Kích hoạt khi có contact mới được tạo.
  * `Contact Updated`: Kích hoạt khi thông tin contact bị thay đổi.
  * `Contact Deleted`: Kích hoạt khi contact bị xóa.
  * `Contact Points Changed`: Kích hoạt khi điểm tiềm năng (Score/Points) của contact tăng hoặc giảm.
* **Email Events (Sự kiện Email):**
  * `Email Open Event`: Kích hoạt khi khách hàng mở đọc email.
  * `Email Click Event`: Kích hoạt khi khách hàng bấm vào một liên kết trong email.
* **Form Events (Sự kiện Biểu mẫu):**
  * `Form Submitted`: Kích hoạt ngay khi khách hàng gửi thông tin qua Form ABOT.
* **Page Events (Sự kiện Trang web):**
  * `Page Hit Event`: Kích hoạt khi khách hàng ghé thăm website có gắn mã tracking ABOT.

***

## 3. Cấu trúc Dữ liệu Payload mẫu (JSON Payload)

Khi sự kiện phát sinh, ABOT sẽ gửi một HTTP POST với header:

```http
Content-Type: application/json
User-Agent: ABOT-Webhook
```

### Ví dụ Payload sự kiện `mautic.lead_post_save_new` (Tạo contact mới):

```json
{
  "mautic.lead_post_save_new": [
    {
      "timestamp": "2026-09-13T14:40:25+00:00",
      "contact": {
        "id": 184509,
        "points": 10,
        "color": "green",
        "fields": {
          "core": {
            "firstname": {
              "value": "Minh",
              "normalizedValue": "Minh"
            },
            "lastname": {
              "value": "Trần",
              "normalizedValue": "Trần"
            },
            "email": {
              "value": "minh.tran@nc-net.vn",
              "normalizedValue": "minh.tran@nc-net.vn"
            },
            "phone": {
              "value": "0912345678",
              "normalizedValue": "0912345678"
            },
            "company": {
              "value": "Công ty Cơ khí NC",
              "normalizedValue": "Công ty Cơ khí NC"
            }
          }
        },
        "tags": [
          "KHACH_HANG_TIEM_NANG",
          "TRIEN_LAM_FBC"
        ],
        "dateIdentified": "2026-09-13 21:40:25"
      }
    }
  ]
}
```

***

## 4. Cách kiểm tra và gỡ lỗi (Debugging Webhooks)

1. **Công cụ thử nghiệm nhận Webhook:**\
   Bạn có thể dùng trang <https://webhook.site> để lấy một URL test miễn phí, dán vào ABOT để xem trực quan cấu trúc gói tin gửi sang.
2. **Kiểm tra lịch sử gửi trong ABOT:**
   * Vào **Bánh răng** ➡️ **Webhooks** ➡️ Bấm vào Webhook bạn vừa tạo.
   * Ở phía dưới trang sẽ có bảng **Recent History (Lịch sử gần đây)** hiển thị mã HTTP trả về từ server đích (200, 404, 500) và số lần thử lại nếu thất bại.