Nhận webhook trên máy bằng SePay CLI

Nhận webhook sandbox của SePay về handler trên localhost bằng sepay webhook listen, không cần tunnel hay URL công khai, kèm gửi lại khi handler lỗi.

||

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).

Trên production

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

Cách webhook về máy bạn
Rendering diagram...
  • listen nhậ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-only khô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ố

FlagKiểuBắt buộcMô tả
--forwardstringTrong scriptĐịa chỉ handler: localhost:3000, localhost:3000/webhooks/sepay hoặc http(s)://.... Trong terminal, bỏ trống thì CLI hỏi
--printboolKhôngIn toàn bộ payload của mỗi thông báo
--eventsstring[]KhôngChỉ chuyển các loại payment_in, payment_out (tiền vào tài khoản ảo cũng là payment_in)
--webhookstringKhôngChỉ 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-retriesintKhôngSố 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
--headersboolKhôngIn header của request chuyển tiếp
--forward-credentialsboolKhôngChuyể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ú

  • listen nhậ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ằng webhook list --active 1; webhook get <xid> hiện Target và Bank account.
  • listen chỉ nhận lần gửi đầu của mỗi giao dịch và các lần gửi lại bằng webhook replay. Lần SePay tự gửi lại khi URL của webhook lỗi không qua listen; xem trong webhook logs.
  • listen nhậ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ằng sepay transaction list.
  • Nhiều webhook cùng áp dụng cho một tài khoản, hoặc hai tiến trình listen chạy cùng lúc, thì handler nhận nhiều request cùng id. Chống xử lý trùng theo id, hoặc lọc bằng --webhook.
  • id trong payload là số nguyên, không phải xid, nên transaction get không nhận. Dùng txn=, hoặc tra theo referenceCode: 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ặc sepay 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ại listen.
  • Dừng listen thì 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ều listen, các lần gửi lại chỉ bị bỏ khi tiến trình listen cuố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ì listen chỉ gửi một lần.
  • Nhiều listen cù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õ retries rồi Enter để xem các lần gửi lại đang chờ; kill <n> hoặc kill all hủy chúng, retries off / retries on ngừ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áiNguyê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 timeHandler 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 productionlisten 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

Tiếp theo

  • Webhook: tạo, sửa webhook, kiểm tra handler bằng webhook test và gửi lại bằng webhook replay
  • Sandbox: giả lập giao dịch để có webhook gửi về