Nhận sự kiện thư qua webhook
Cấu hình endpoint để biết thư tới hay hỏng ngay trong mã nguồn, chọn đúng sự kiện cần nghe và xác minh chữ ký để không nhận nhầm dữ liệu giả.
Lệnh gọi gửi thư trả về "đã nhận để gửi", không phải "đã tới nơi". Webhook báo ngược chuyện xảy ra sau đó.
Chuẩn bị
- Một địa chỉ HTTP công khai nhận được yêu cầu
POST, hoặc một kênh chat để nhận thông báo - Đã gửi được thư. Xem Gửi thư đầu tiên qua Email API
Chọn kênh
Vào Email API → Webhooks → Thêm Webhook mới. Ngoài HTTP còn gửi thẳng được vào kênh chat.
| Kênh | Hợp với |
|---|---|
| HTTP | ứng dụng tự xử lý — đánh dấu địa chỉ hỏng, dừng gửi lại |
| Kênh chat của nhóm | người theo dõi, không phải máy xử lý |
Kênh chat tiện để cảnh báo nhưng đừng dùng thay HTTP: con người không cập nhật được cơ sở dữ liệu.
Chọn sự kiện
Bảy sự kiện — chọn đúng thứ cần xử lý, đừng chọn hết.
| Sự kiện | Khi nào bắn | Bạn nên làm gì |
|---|---|---|
email.sent | ngay khi hệ thống nhận | thường không cần — bạn đã biết từ mã trả về |
email.delivered | sau khi nơi nhận báo đã nhận | ghi nhận, nếu cần |
email.opened | người nhận mở thư — bắn mỗi lần mở | đếm lượt mở, nếu cần |
email.clicked | người nhận bấm liên kết trong thư — bắn mỗi lần bấm | đếm lượt bấm, nếu cần |
email.bounced | thư bị trả lại | đánh dấu địa chỉ hỏng, ngừng gửi |
email.complained | người nhận báo cáo là thư rác | ngừng gửi cho địa chỉ đó ngay |
email.failed | không gửi được | xem lý do, sửa rồi thử lại |
email.bounced và email.complained được chọn sẵn vì đó là hai sự kiện bắt buộc phải xử lý
nếu muốn giữ uy tín gửi thư.
email.complained nghiêm trọng nhất: tiếp tục gửi cho người đã báo cáo bạn là thư rác làm hỏng uy
tín của cả tên miền.
Xác minh chữ ký
Sau khi tạo, hệ thống hiện một secret chỉ hiển thị một lần — lưu ngay như lưu khoá API. Sửa webhook về sau không đổi secret.
Secret dùng để kiểm chữ ký ở header X-CloudFly-Signature. Endpoint phải kiểm chữ ký trước khi
tin nội dung.
Địa chỉ webhook là công khai
Không kiểm chữ ký thì bất kỳ ai biết địa chỉ đó đều gửi được sự kiện email.bounced giả, và ứng
dụng của bạn sẽ tự tay đánh dấu hỏng những địa chỉ khách hàng đang dùng tốt.
Viết endpoint cho đúng
Ba điều hệ thống trông đợi ở endpoint của bạn:
- Trả về nhanh. Trả
2xxtrong 10 giây; việc nặng thì đẩy vào hàng đợi rồi trả lời ngay. - Chịu được trùng lặp. Sự kiện có thể tới hơn một lần, ví dụ khi bấm Gửi lại. Xử lý theo
email_id+type(vớiemail.opened/email.clickedthêmtimestamp). - Không có gửi lại tự động. Mỗi sự kiện chỉ gửi một lần; mã khác
2xx, quá 10 giây hay chuyển hướng đều bị ghi là lỗi.
Theo dõi và gỡ lỗi
Trang webhook có lịch sử giao dịch với cột ID Giao dịch, URL Đích và Lần gửi. Lịch sử lưu 30 ngày.
| Triệu chứng | Nguyên nhân thường gặp |
|---|---|
| Dòng báo Lỗi gửi | endpoint trả mã khác 2xx, quá 10 giây hoặc không kết nối được — sửa endpoint rồi bấm Gửi lại trên dòng đó |
| Cột Lần gửi lớn hơn 1 | dòng đó đã được bấm Gửi lại — mỗi lần bấm cộng thêm 1, hệ thống không tự gửi lại |
| Chưa có lịch sử nào | chưa có sự kiện nào thuộc loại bạn đã chọn xảy ra |
| Endpoint bị tạm ngưng | dùng nút Kích hoạt endpoint để bật lại |
Tạm ngưng là bỏ lỡ sự kiện
Nút Tạm ngưng endpoint dừng gửi mà không xoá cấu hình hay secret, nhưng sự kiện xảy ra trong lúc tạm ngưng không được lưu và không gửi bù. Đang sửa hệ thống nhận mà vẫn cần sự kiện thì cứ để endpoint chạy, sửa xong bấm Gửi lại các dòng lỗi.
Kiểm tra kết quả
- Gửi một thư tới một địa chỉ chắc chắn không tồn tại trong tên miền bạn kiểm soát
- Chờ vài phút
- Endpoint của bạn nhận được
email.bounced, và lịch sử giao dịch có một dòng thành công - Địa chỉ đó xuất hiện trong danh sách chặn
Bước 4 là cách chéo để chắc chắn hệ thống và ứng dụng của bạn đang nhìn cùng một sự thật.