Muốn nhận webhook SePay ngay trên máy đang code mà không dựng tunnel hay URL công khai, chạy sepay webhook listen. Lệnh chuyển mỗi lần gửi webhook vào handler trên máy bạn, để bạn kiểm tra code xử lý webhook trước khi đưa lên server.
webhook listen chỉ chạy trên sandbox. Bạn cần đăng nhập, công ty cần bật Test Mode (xem Test Mode), có tài khoản ngân hàng sandbox và ít nhất một webhook đang bật. Cách nhanh nhất là sepay sandbox init --with-webhook-listen: lệnh tạo cả tài khoản lẫn webhook không có URL (sandbox init).
webhook listen không chạy trên production: CLI dừng với exit code 2 trước khi gọi server, và server cũng trả HTTP 404 This endpoint is only available in the sandbox environment cho mọi lần gọi listen trên production. pg ipn listen và bankhub ipn listen cũng vậy. Trên production, xem từng lần gửi và phản hồi của URL webhook bằng webhook logs hoặc lịch sử gửi webhook trên Dashboard.
Cách chuyển webhook về máy
listennhận bản sao của mỗi lần gửi qua kết nối mở từ máy bạn ra SePay, nên không cần tunnel.- Handler nhận cùng body và header như URL của webhook, nên kiểm tra chữ ký giống production.
- Handler trả gì cũng không ảnh hưởng lần gửi (1). Webhook
--listen-onlykhông có URL nên chỉ có nhánh (2).
Cấu trúc payload có ở Tích hợp webhook, cách kiểm tra chữ ký có ở Xác thực webhook.
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--forward | string | Trong script | Địa chỉ handler: localhost:3000, localhost:3000/webhooks/sepay hoặc http(s)://.... Trong terminal, bỏ trống thì CLI hỏi |
--print | bool | Không | In toàn bộ payload của mỗi thông báo |
--events | string[] | Không | Chỉ chuyển các loại payment_in, payment_out (tiền vào tài khoản ảo cũng là payment_in) |
--webhook | string | Không | Chỉ chuyển lần gửi của webhook này (xid). CLI không kiểm tra xid; xid sai thì không thấy lần gửi nào |
--forward-retries | int | Không | Số lần gửi lại khi chuyển tới handler thất bại (xem Gửi lại trên máy bạn). Mặc định 7, tối đa 10; 0 là một lần |
--headers | bool | Không | In header của request chuyển tiếp |
--forward-credentials | bool | Không | Chuyển Authorization, X-Secret-Key tới handler không phải loopback; mặc định không chuyển |
Các flag khác (--skip-tls-verify cho handler https trên máy bạn, --reconnect-max) xem bằng sepay webhook listen --help.
Ví dụ
$ sepay webhook listen --forward localhost:3000/webhooks/sepay --printDelivering for: ACB · 0000000001 · NGUYEN VAN A (sandbox)Any other bank account of this company produces no events.✓ Listening for sandbox events → http://localhost:3000/webhooks/sepay (Ctrl+C to stop · retries+enter to manage)14:22:07 payment_in → http://localhost:3000/webhooks/sepay 200 12ms txn=a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98 wh=5f0e2a7b-xxxx-xxxx-xxxx-3c9d81e04b6a { "accountNumber": "...", "accumulated": 0, "code": "DH1709", ... }txn= là xid giao dịch; wh= là xid webhook đã gửi. Ctrl+C dừng lệnh. Lệnh cũng tự dừng với exit code 4 khi phiên đăng nhập bị thu hồi (access_revoked); chạy sepay login rồi mở lại listen.
Ghi chú
listennhận thông báo của mọi tài khoản ngân hàng trong công ty, kể cả tiền vào VA (payment_in), miễn có webhook đang bật áp dụng cho tài khoản đó. Kiểm tra bằngwebhook list --active 1;webhook get <xid>hiệnTargetvàBank account.listenchỉ nhận lần gửi đầu của mỗi giao dịch và các lần gửi lại bằngwebhook replay. Lần SePay tự gửi lại khi URL của webhook lỗi không qualisten; xem trongwebhook logs.listennhận bản sao để kiểm thử, nên có thể bỏ lỡ sự kiện khi kết nối chậm hoặc lỗi, và sự kiện đó không được gửi lại. Webhook chính thức không bị ảnh hưởng; đối chiếu giao dịch bằngsepay transaction list.- Nhiều webhook cùng áp dụng cho một tài khoản, hoặc hai tiến trình
listenchạy cùng lúc, thì handler nhận nhiều request cùngid. Chống xử lý trùng theoid, hoặc lọc bằng--webhook. idtrong payload là số nguyên, không phải xid, nêntransaction getkhông nhận. Dùngtxn=, hoặc tra theoreferenceCode:sepay transaction list --reference-number <referenceCode>.
Gửi lại trên máy bạn
Handler lỗi thì listen gửi lại theo lịch gửi lại của SePay: mặc định 7 lần, tối đa 10 lần (kéo dài khoảng 2,4 giờ).
- Mỗi lần gửi lại giữ nguyên từng byte, kể cả chữ ký và timestamp. Handler từ chối timestamp cũ sẽ từ chối các lần gửi lại muộn.
- Phản hồi không phải 2xx chỉ được gửi lại khi webhook bật
retry_conditions.non_2xx_status_code; lỗi kết nối hoặc hết thời gian chờ luôn được gửi lại. Bật bằng công tắc Tự động gửi lại khi server trả lỗi trên my.sepay.vn hoặcsepay api(xem cách bật).listenđọc thiết lập này lúc khởi động, nên đổi xong thì khởi động lạilisten. - Dừng
listenthì các lần gửi lại đang chờ bị bỏ, và khởi động lại không gửi tiếp. Nếu bạn chạy nhiềulisten, các lần gửi lại chỉ bị bỏ khi tiến trìnhlistencuối cùng dừng. Tối đa 500 lần gửi (24 MiB) chờ cùng lúc. - Chỉ gửi lại khi handler ở trên máy bạn (loopback). Handler ở máy khác thì
listenchỉ gửi một lần. - Nhiều
listencùng trỏ vào một handler: mỗi tiến trình gửi lần đầu, chỉ một tiến trình gửi các lần gửi lại. - Trong terminal, gõ
retriesrồi Enter để xem các lần gửi lại đang chờ;kill <n>hoặckill allhủy chúng,retries off/retries onngừng hoặc bật lại việc lên lịch gửi lại mới.
Thông báo lỗi
| Thông báo hoặc trạng thái | Nguyên nhân |
|---|---|
not responding (is your handler running?) | Handler không chạy hoặc chạy ở cổng khác |
did not answer in time | Handler nhận request nhưng không trả lời kịp |
failed TLS verification (an untrusted or mismatched certificate) | --forward dùng https mà chứng chỉ của handler không được tin cậy hoặc không khớp tên miền |
webhook listen is sandbox-only; drop --env production | listen chỉ chạy trên sandbox. Bỏ --env production; nếu môi trường mặc định là production thì thêm --env sandbox. Trên production, xem lần gửi bằng webhook logs |
Status 404 trong dòng kết quả | Sai đường dẫn trong --forward |