Vào Dashboard → Tích hợp → Webhooks để tạo và quản lý webhook. Tạo webhook mới qua form 4 bước, còn các thao tác sửa, sao chép, gửi thử nằm trong menu ⋮ ở mỗi dòng.
Form tạo 4 bước
Bấm Thêm webhook.
Bước 1: Cơ bản
- Tên: gợi nhớ, ví dụ "Thanh toán đơn hàng website"
- URL: endpoint nhận webhook, phải HTTPS cho production
- Loại sự kiện: xem Loại sự kiện bên dưới
- Content-Type: để mặc định
application/json(chi tiết nếu cần đổi) - Tự động gửi lại: bật nếu muốn SePay retry khi server trả lỗi. Chi tiết lịch retry: Xử lý lỗi
Bước 2: Tài khoản
Chọn tài khoản ngân hàng nào kích hoạt webhook.
- Tất cả tài khoản: mọi tài khoản đều kích hoạt webhook, tài khoản ngân hàng mới liên kết sau cũng tự áp dụng mà không cần chỉnh lại.
- Chọn cụ thể: chọn từng tài khoản, cấu hình VA riêng từng ngân hàng.
Bạn cũng cấu hình bộ lọc mã thanh toán và "Bỏ qua giao dịch không có mã" tại bước này. Xem Bộ lọc bên dưới.
Chi tiết về tài khoản + VA: Tài khoản ngân hàng.
Bước 3: Bảo mật
Chọn cách SePay xác thực với endpoint của bạn:
- Không xác thực: chỉ dùng khi test
- API Key: header
Authorization: Apikey ... - HMAC-SHA256 (khuyến nghị): chữ ký trong header
- OAuth 2.0: Bearer token qua token endpoint
So sánh và code mẫu: Xác thực.
Bước 4: Cảnh báo
- Bật/tắt cảnh báo
- Ngưỡng lỗi liên tiếp trước khi gửi (1–20, mặc định 3)
- Chọn kênh nhận: Telegram, Slack, Discord
Cấu hình kênh cảnh báo: Giám sát.
Loại sự kiện
| Loại | Gửi webhook khi |
|---|---|
| Tiền vào | Có tiền chuyển đến tài khoản |
| Tiền ra | Có tiền chuyển đi |
| Cả hai | Có bất kỳ giao dịch nào |
Tiền ra có hai điều kiện: chỉ hỗ trợ Sacombank, TPBank, VietinBank và phải dùng TKP (VA nội dung, không dùng được VA chính thức). Xem Lưu ý khi chọn Chỉ tiền ra.
Với webhook xác thực thanh toán, thường chỉ cần chọn Tiền vào.
Bộ lọc
Lọc theo tiền tố mã thanh toán
Yêu cầu SePay chỉ gửi webhook khi mã thanh toán bắt đầu bằng tiền tố nhất định.
Ví dụ: khách chuyển khoản nội dung GCDONHANG001. SePay nhận diện được mã GCDONHANG001. Webhook cấu hình tiền tố GC → mã bắt đầu bằng GC → gửi.
| Tiền tố | Mã thanh toán | Kết quả |
|---|---|---|
GC | GCDONHANG001 | Gửi |
GC | ORDERDONHANG001 | Bỏ qua |
GC, ORDER | ORDERDONHANG001 | Gửi (khớp ORDER) |
| (không chọn) | Bất kỳ | Gửi hết |
Trước hết cần cấu hình cấu trúc mã tại Công ty → Cấu hình chung → Cấu trúc mã thanh toán. Sau đó ở bước Tài khoản khi tạo webhook sẽ có mục chọn tiền tố.
Tiền tố phân biệt hoa thường, ví dụ GC và gc được tính là hai tiền tố khác nhau.
Bỏ qua giao dịch không có mã
Bật thì SePay chỉ gửi webhook cho giao dịch có mã thanh toán. Giao dịch nội dung trống hoặc không khớp cấu trúc sẽ bị bỏ qua.
Thứ tự kiểm tra
Khi có giao dịch mới, SePay kiểm tra lần lượt:
- Giao dịch có thuộc tài khoản đã cấu hình?
- Nếu có cấu hình VA, giao dịch có khớp VA nào?
- Loại sự kiện (tiền vào/ra) có đúng?
- Giao dịch có mã thanh toán không? (nếu bật bỏ qua)
- Mã có bắt đầu bằng tiền tố đã chọn?
Webhook chỉ được gửi khi tất cả điều kiện ở trên đều khớp.
Gửi thử
Bấm ⋮ → Gửi thử để kiểm tra endpoint trước khi có giao dịch thật. SePay gửi payload mẫu đến URL và hiển thị kết quả (HTTP status và response body) ngay.
Cấu trúc JSON giống hệt, nhưng id là số mock (thường 0), các trường khác là data mẫu. Đừng viết cứng giá trị test vào code. Sau khi gửi thử thành công, vẫn nên thử lại với giao dịch thật (chuyển số nhỏ vào tài khoản).
Quản lý webhook
Tiếp theo
- Tích hợp webhook: cấu trúc payload, phản hồi hợp lệ, chống trùng lặp
- Xác thực: HMAC-SHA256, API Key, OAuth 2.0
- Tài khoản ngân hàng: danh sách ngân hàng hỗ trợ + VA