Webhook trong Admin OneMail
Khai báo địa chỉ nhận dữ liệu để người dùng đẩy một thư sang hệ thống khác ngay từ hòm thư.
Mục Webhook trong giao diện quản trị OneMail khai báo các địa chỉ nhận dữ liệu bên ngoài. Webhook đang bật sẽ xuất hiện trong menu thao tác của từng thư ở hòm thư — người dùng bấm chọn là OneMail đẩy nội dung thư đó sang hệ thống nhận, dùng để mở phiếu hỗ trợ, ghi vào phần mềm quản lý khách hàng, hoặc kích hoạt một quy trình tự động.
Vào ở đâu
Mở Admin → Webhook.
Thêm webhook
- Bấm Thêm Webhook.
- Chọn Icon — biểu tượng hiện cạnh tên webhook trong danh sách và trong menu thao tác thư.
- Nhập Tên — bắt buộc; đây là chữ người dùng nhìn thấy trong menu thao tác thư nên đặt theo việc mà webhook làm.
- Nhập URL — bắt buộc, phải là địa chỉ hợp lệ. Sai định dạng, biểu mẫu báo lỗi ngay dưới ô nhập.
- Chọn Method —
GET,HEAD,POST,PUT,DELETE,OPTIONS,PATCH. - Bật hoặc tắt ô Hiển thị — quyết định webhook có xuất hiện với người dùng hay không.
- Bấm Lưu lại.
Quản lý danh sách
- Bật/tắt nhanh: gạt công tắc ở cột Trạng thái. Tắt thì webhook biến mất khỏi menu thao tác thư của người dùng nhưng khai báo vẫn giữ nguyên.
- Sửa: bấm nút bút chì → hộp thoại Chỉnh sửa Webhook mở với dữ liệu cũ → sửa → Lưu lại.
- Xoá: bấm nút thùng rác → hộp thoại xác nhận hiện tên webhook → xác nhận.
- Tìm: gõ vào ô tìm kiếm phía trên bảng.
- Lọc theo phương thức: bấm mũi tên cạnh tiêu đề cột Phương thức → chọn Tất cả hoặc một phương thức cụ thể.
Người dùng gọi webhook thế nào
Trong hòm thư, mở một thư → menu thao tác của thư → mục Webhook → chọn tên webhook. OneMail gửi yêu cầu tới địa chỉ đã khai báo và báo "Đã gửi tới <tên webhook>" khi xong.
Dữ liệu gửi đi ở dạng JSON, gồm:
| Trường | Nội dung |
|---|---|
event | Luôn là mail_action. |
triggered_by | Tài khoản OneMail đã bấm gọi: email, tên hiển thị, tên miền. |
triggered_at | Thời điểm gọi. |
mail | Thông tin thư đã tách sẵn: mã thư, chủ đề, thời gian, người gửi, danh sách người nhận, danh sách nhận bản sao. |
message | Bản gốc dữ liệu thư, giữ nguyên để phía nhận tự đọc thêm khi cần. |
Yêu cầu do máy chủ OneMail phát đi, không phát từ trình duyệt của người dùng — nên hệ thống nhận không cần cấu hình cho phép gọi chéo miền.
Giới hạn & lưu ý
- Địa chỉ chỉ nhận giao thức
httphoặchttps. - Không trỏ được vào địa chỉ nội bộ —
localhost, dải IP riêng, địa chỉ liên kết cục bộ đều bị từ chối với thông báo "Webhook không được trỏ tới địa chỉ nội bộ". - Hệ thống nhận phải phản hồi trong khoảng 10 giây, quá thời gian OneMail báo "Webhook endpoint không phản hồi (timeout)".
- Hệ thống nhận trả về mã lỗi từ 400 trở lên thì OneMail báo gửi thất bại kèm mã đó; chuyển hướng cũng bị coi là thất bại.
- Webhook khai báo áp cho toàn tổ chức — mọi tài khoản đều thấy trong menu thao tác thư, không đặt riêng theo từng người.
- Nội dung thư được gửi ra hệ thống bên ngoài. Chỉ khai báo địa chỉ thuộc hệ thống tin cậy của tổ chức.