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 là cách hệ thống báo ngược lại cho bạn chuyện gì xảy ra sau đó, mà không phải hỏi dò liên tục.
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, hệ thống gửi thẳng được vào các kênh chat phổ biến.
| 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 cho việc cảnh báo, nhưng đừng dùng nó thay cho HTTP: con người không cập nhật được cơ sở dữ liệu của bạn mỗi khi có một địa chỉ hỏng.
Chọn sự kiện
Năm sự kiện, và bạn nên chọn đúng thứ cần xử lý chứ khô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.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 |
Hai sự kiện được chọn sẵn khi bạn mở màn hình thêm mới là email.bounced và email.complained —
đó không phải mặc định ngẫu nhiên. Chúng là hai sự kiện bắt buộc phải xử lý nếu bạn muốn giữ
được uy tín gửi thư lâu dài.
email.complained là sự kiện 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, không riêng một chiến dịch.
Xác minh chữ ký
Sau khi tạo, hệ thống hiện một secret kèm dòng nhắc rằng nó chỉ hiển thị một lần. Lưu ngay như lưu khoá API.
Secret dùng để kiểm chữ ký đi kèm mỗi yêu cầu, ở header X-CloudFly-Signature. Endpoint của bạn
phải kiểm chữ ký đó trước khi tin nội dung.
Lý do rất thực tế: đị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.
Sửa webhook về sau không đổi secret — chỉ khi tạo mới.
Viết endpoint cho đúng
Ba điều hệ thống trông đợi ở endpoint của bạn:
- Trả về nhanh. Xử lý nặng thì đẩy vào hàng đợi rồi trả lời ngay, đừng xử lý xong mới trả lời.
- Chịu được trùng lặp. Cùng một sự kiện có thể tới hơn một lần. Xử lý theo mã sự kiện, đừng cộng dồn mù quáng.
- Trả mã thành công khi đã nhận. Trả mã lỗi sẽ khiến hệ thống gửi 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 |
|---|---|
| Cột Lần gửi tăng dần nhiều lần | endpoint trả mã lỗi, hệ thống đang 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 |
Nút Tạm ngưng endpoint hữu ích khi bạn đang sửa hệ thống nhận: nó dừng gửi mà không xoá cấu hình và không mất secret.
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.