NỘI DUNG

• Giới thiệu chung
• Hướng dẫn sử dụng

Giới thiệu chung

Webhook là công cụ giúp hệ thống gửi dữ liệu tự động đến một endpoint bên ngoài khi xảy ra sự kiện. Với webhook, dữ liệu được đẩy đi ngay lập tức mà không cần kiểm tra liên tục, giúp tiết kiệm tài nguyên và tăng hiệu quả.

Trong giao diện cài đặt webhook của phần mềm này, có hai phần chính:

1. Thông tin chung: Bao gồm các trường cần thiết để cấu hình webhook, như tên webhook, phương thức gửi dữ liệu (thường là POST), URL endpoint, đối tượng theo dõi và trạng thái hoạt động. Cài đặt này giúp định nghĩa rõ mục đích và cấu hình cơ bản của webhook.

2. Cài đặt nâng cao: Bao gồm các trường như Header Request và Body Request, nơi bạn có thể thêm các khóa và giá trị tùy chỉnh. Điều này cho phép bạn kiểm soát chi tiết về cách gửi dữ liệu và xác thực tính hợp lệ của yêu cầu, chẳng hạn như sử dụng chữ ký xác thực.

Ứng dụng của Webhook

• Tích hợp hệ thống: Webhook kết nối dữ liệu với CRM, ERP, hoặc ứng dụng marketing, gửi sự kiện ngay lập tức để xử lý.
• Theo dõi sự kiện: Thông báo trạng thái nhiệm vụ như tạo mới, hoàn thành, hoặc thay đổi trạng thái.
• Bảo mật: Dùng chữ ký hoặc token xác thực để đảm bảo an toàn dữ liệu.
• Tự động hóa: Kích hoạt quy trình khi sự kiện như đơn hàng thành công xảy ra.

Hướng dẫn sử dụng

1. Hướng dẫn Cài đặt thông tin chung

Hình ảnh: Tab Thông tin chung của Form tạo mới webhook

Bảng mô tả các trường thông tin

Lưu ý:

1. Phương thức (Method) và Đường dẫn (URL): Khi chọn phương thức HTTP (ví dụ POST), URL cần được thiết lập để webhook biết phải gửi dữ liệu đến đâu. Hai trường này cần có sự liên kết để xác định cách gửi dữ liệu.

2. Trường Đối tượng và Trường Cài đặt sự kiện: Đối tượng là loại dữ liệu hoặc sự kiện mà bạn muốn theo dõi. Trong Cài đặt sự kiện, bạn có thể chọn các sự kiện cụ thể liên quan đến đối tượng này để kích hoạt webhook. Nếu không chọn Đối tượng, bạn vẫn có thể cài đặt sự kiện nhưng sẽ hạn chế các tùy chọn sự kiện cụ thể.

3. Trạng thái: Trạng thái phải được đặt là "Đang hoạt động" thì webhook mới có thể hoạt động. Nếu không, các sự kiện sẽ không kích hoạt webhook.

4. Cài đặt sự kiện: Ít nhất phải có một cài đặt sự kiện để webhook có mục tiêu cụ thể và biết khi nào kích hoạt.

Hình ảnh: Ví dụ sau khi cài đặt màn Cài đặt chung

2.  Hướng dẫn cài đặt nâng cao

Hình ảnh: Tab Cài đặt nâng cao của Form tạo mới webhook 

Màn hình này cho phép người dùng tùy chỉnh thêm các cài đặt kỹ thuật của webhook:

• Header Request Default:

• Hệ thống tự động thêm một khóa Header mặc định: X-1Office-Signature với giá trị định sẵn.

• Phục vụ cho mục đích xác thực hoặc bảo mật.

• Ví dụ

• Header Requests:

• Người dùng có thể thêm các cặp "Khóa" và "Giá trị" tùy chỉnh cho phần header của request.

• Mỗi dòng tương ứng một cặp, có thể thêm nhiều cặp với nút "+".

• Body Requests:

• Tương tự Header, người dùng định nghĩa các cặp "Khóa" và "Giá trị" cho phần thân (body) của request.

• Cho phép gửi dữ liệu bổ sung khi webhook được kích hoạt.

• Thời gian lưu lịch sử webhook:

• Dropdown cho phép chọn khoảng thời gian lưu trữ dữ liệu lịch sử hoạt động của webhook (ví dụ: 1 tháng).

Lưu ý:

1. Trường bắt buộc:

• Tên webhook, Phương thức, Đường dẫn, Đối tượng.

• Nếu các trường này không được điền, hệ thống sẽ hiển thị thông báo lỗi.

2. Xác thực URL:

• Trường URL phải đảm bảo định dạng hợp lệ (ví dụ: phải bắt đầu với http:// hoặc https://).

3. Header và Body Requests:

• Không bắt buộc, nhưng phải đảm bảo khóa không trùng lặp trong từng nhóm.

4. Giới hạn lịch sử webhook:

• Giá trị lưu trữ lịch sử phải nằm trong các tùy chọn mà hệ thống cung cấp.

Hình ảnh: Ví dụ Cài đặt nâng cao của Form tạo mới webhook 

3. Hướng dẫn xem danh sách Webhook

Sau khi tạo xong bạn sẽ thấy webhook vừa tạo ở màn danh sách 

Màn danh sách giúp bạn có thể

• Xem danh sách các webhook đã cấu hình, gồm thông tin: tên, đường dẫn, phương thức, đối tượng, trạng thái, số lần gọi, thời gian gọi cuối, ngày tạo.

• Cho phép tìm kiếm, lọc, và xuất danh sách webhook.

4. Hướng dẫn xem lịch sử hoạt động của webhook

Sau khi webhook nhận được dữ liệu sẽ lưu lại lịch sử như sau: 

• Webhook lưu lại lịch sử nhận/gửi dữ liệu, bạn có thể xem được Trạng thái, thời gian gửi, số lần quá thời gian xử lí, log trả về, dữ liệu...

• Ví dụ:

  • Lỗi "Token not found": Kiểm tra URL endpoint và token.

  • Trạng thái Thất bại (Failed): Kiểm tra log trả về (VD: lỗi 404, 500)...

Ví Dụ Minh Hoạ

• Cài đặt thông tin chung:

  • Tên: Webhook_ThongBaoDonHangMoi

  • URL: https://cloud-cloud.1office.vn/

  • Phương thức: POST

  • Đối tượng: Đơn hàng

  • Sự kiện: Sau khi tạo mới

  • Trạng thái: Đang hoạt động

• Cài đặt nâng cao:

  • Header: Authorization: Bearer

  • Body: { "order_id": 12345 }

  • Lưu lịch sử: 1 tháng