Quản lý webhook bằng SePay CLI

Tạo, sửa, xóa webhook SePay bằng SePay CLI, chọn tài khoản và VA nhận thông báo, xem lịch sử gửi, kiểm tra handler và gửi lại webhook.

||

Nhóm lệnh webhook tạo, sửa, xóa webhook, xem lịch sử gửi, gửi lại một lần gửi cũ, và kiểm tra handler bằng webhook test.

Các lệnh chạy trên cả sandbox và production, trừ listen, create --listen-only và test chỉ chạy trên sandbox. Trên production, create, update, delete, replay cần scope webhook:write, các lệnh còn lại cần read. Bạn cần đăng nhập. Trên sandbox, công ty cần bật Test Mode (xem Test Mode) và có tài khoản ngân hàng sandbox (sandbox init).

Muốn nhận webhook ngay trên máy đang code, xem Nhận webhook trên máy (webhook listen, chỉ sandbox).

Lệnh

LệnhMô tảMôi trường
webhook createTạo webhookCả hai
webhook listenNhận webhook trên máy bạnSandbox
webhook testTạo giao dịch thử và kiểm tra phản hồi của handlerSandbox
webhook logsLịch sử gửiCả hai
webhook replayGửi lại webhookCả hai
webhook updateSửa webhookCả hai
webhook list, get <xid>, delete <xid>Xem, xóa webhookCả hai

webhook list lọc theo trạng thái bằng --active 0 hoặc --active 1. webhook delete hỏi xác nhận trước khi xóa. Trên sandbox, không có terminal thì cần --yes; trên production, lệnh theo luật xác nhận.

webhook create

Tạo webhook gửi tới URL của bạn (--url), hoặc webhook không có URL chỉ nhận qua webhook listen (--listen-only, chỉ sandbox).

Tham số

FlagKiểuBắt buộcMô tả
--bank-modestringTrong scriptsingle | multi | all: một, nhiều hoặc mọi tài khoản ngân hàng. Trong terminal, bỏ trống thì CLI hỏi
--bank-accountstring[]Với single, multiXid tài khoản; lặp flag để chọn nhiều
--bank-configstring[]KhôngMỗi tài khoản nhận thông báo gì, dạng <xid>=<số tài khoản>:<VA>. Lặp flag cho từng tài khoản. Xem Chọn tài khoản nhận thông báo
--va-xidstring[]Với VA listXid VA cần nhận; lặp flag để chọn nhiều
--event-typestringKhôngall | in | out. Mặc định all
--urlstringTrừ khi --listen-onlyURL máy chủ của bạn, truy cập được từ Internet; tên miền phải phân giải được qua DNS công khai
--listen-onlyboolKhôngKhông có URL; chỉ nhận qua webhook listen (chỉ sandbox)
--auth-typestringKhôngnone | apikey | hmac | oauth2
--secretstringVới apikey, hmacSecret dùng chung; - đọc từ stdin để không lưu vào lịch sử lệnh
--namestringKhôngTên webhook

Các flag khác (--content-type, --only-va, --prefix-filter, --skip-if-no-code, --verify-payment, --oauth2-*) xem bằng sepay webhook create --help; ý nghĩa từng tùy chọn của webhook có ở Tạo webhook.

Ví dụ

Tạo webhook không có URL, chỉ nhận qua webhook listen:

$ sepay webhook create --listen-only --bank-mode all --event-type in

Tạo webhook gửi tới URL của bạn, ký bằng HMAC. Secret truyền qua stdin từ biến môi trường SECRET:

$ printf '%s' "$SECRET" | sepay webhook create --url https://api.congty.vn/webhooks/sepay \--bank-mode all --event-type in --auth-type hmac --secret -

Tạo webhook cho một tài khoản chỉ nhận tiền qua VA, chỉ nhận hai VA:

$ sepay webhook create --url https://api.congty.vn/webhooks/sepay --bank-mode single \--bank-account <bank-account-xid> --bank-config <bank-account-xid>=off:list \--va-xid <va-xid-1> --va-xid <va-xid-2>

Lệnh in ✓ Created webhook <xid>..

Tạo webhook trong terminal

Chạy sepay webhook create trong terminal, CLI hỏi những gì bạn chưa truyền bằng flag, theo thứ tự:

  1. Delivery: Send events to my URL hoặc Watch events locally with "sepay webhook listen" (no URL). Chỉ hỏi trên sandbox.
  2. Webhook URL: bỏ trống hoặc URL sai thì CLI hỏi lại ngay, không đợi tới lúc gửi lên SePay mới báo lỗi.
  3. Webhook name (optional).
  4. Authentication: None, API key, HMAC signature hoặc OAuth2. Webhook nhận qua listen không có OAuth2. Secret nhập ẩn, không hiện trên màn hình.
  5. Targeting mode: single, multi hoặc all.
  6. Với single và multi: chọn tài khoản, rồi chọn mỗi tài khoản nhận thông báo gì trong form What each bank account notifies (mục dưới).

CLI không hỏi loại giao dịch; mặc định là all, đổi bằng --event-type. Trên production, CLI in ! live: create webhook targets PRODUCTION rồi hỏi xác nhận trước khi tạo. Lệnh tạo không có id nên trên production chỉ chạy trong terminal; --yes không xác nhận được.

Chọn tài khoản nhận thông báo

Mỗi tài khoản trong webhook single hoặc multi có hai lựa chọn, giống form tạo webhook trên my.sepay.vn:

  • Account number: nhận giao dịch chuyển thẳng vào số tài khoản.
  • Virtual accounts: All, including ones created later (mọi VA, kể cả VA tạo sau), Only selected (chỉ các VA bạn tick) hoặc None.

Mặc định mỗi tài khoản nhận cả số tài khoản lẫn mọi VA. Form chỉ đưa ra lựa chọn mà tài khoản đó nhận được; xem tài khoản thuộc loại nào ở dòng Notifies của sepay bank-account get <xid>:

Tài khoảnTrong form--bank-config hợp lệ
Chỉ nhận qua VA: tài khoản MSB, KienLongBank, OCB, BIDV cá nhân và hộ kinh doanh, Vietcombank, chỉ khi kết nối API, không có SMSGhi virtual accounts only, ô Account number khóa ở trạng thái tắt. Chưa có VA nào thì ghi virtual accounts only · none issued yet, so nothing is notified until one isoff:all, off:list
Nhận cả số tài khoản lẫn VA (đa số ngân hàng kết nối API, mọi tài khoản kết nối SMS)Chọn tự doMọi tổ hợp trừ off:none
Không có VAGhi no virtual accounts, chỉ nhận số tài khoảnon:none

Trong form, ↑/↓ di chuyển, Space bật hoặc tắt ô đang chọn, ←/→ đổi chế độ VA, Enter xong. Only selected chỉ có khi tài khoản có ít nhất một VA đang hoạt động; chọn nó thì danh sách VA của tài khoản hiện ngay bên dưới để tick. CLI không nhận Enter khi còn tài khoản không nhận được gì, ví dụ chọn Only selected mà chưa tick VA nào, và in lý do ở cuối form. Xong, mỗi tài khoản còn lại một dòng tóm tắt, ví dụ account number + all virtual accounts.

Trong script, dùng --bank-config thay cho form. CLI kiểm tra trước khi gửi và từ chối kèm lý do khi cấu hình không hợp với tài khoản, ví dụ off:none, hoặc list mà không có --va-xid nào thuộc tài khoản đó (va mode list needs at least one of this account's virtual accounts in --va-xid).

Gửi thẳng bằng sepay api thì SePay vẫn kiểm tra và trả 422 validation_error khi cấu hình không nhận được gì, ví dụ bank account <xid> would receive nothing: set receive_primary true or va_mode all or list hoặc bank account <xid> only delivers virtual-account transactions; va_mode must be all or list.

webhook update

Sửa webhook. Chỉ các flag bạn truyền mới thay đổi, phần còn lại giữ nguyên.

$ sepay webhook update <webhook-xid> --url https://api.congty.vn/webhooks/sepay-moi$ sepay webhook update <webhook-xid> --event-type in --skip-if-no-code

Đổi cấu hình của một tài khoản; các tài khoản khác giữ cấu hình cũ:

$ sepay webhook update <webhook-xid> --bank-config <bank-account-xid>=off:list --va-xid <va-xid>

Lệnh nhận cùng flag với webhook create. Trên sandbox, --listen-only chuyển webhook sang chỉ nhận qua webhook listen; truyền --url để chuyển lại về gửi tới URL. Viết tắt: webhook edit. Không truyền <webhook-xid> thì CLI cho chọn từ danh sách webhook khi chạy trong terminal; trong script thì bắt buộc.

Chạy sepay webhook update <webhook-xid> không kèm flag trong terminal, CLI hỏi What do you want to edit? với danh sách mục kèm giá trị đang lưu: tên, URL, loại giao dịch, định dạng dữ liệu, xác thực thanh toán, bỏ qua giao dịch không có mã thanh toán, tiền tố mã thanh toán, xác thực và Targeting. Chọn Targeting thì CLI hỏi lại chế độ, tài khoản và mở form Chọn tài khoản nhận thông báo, bắt đầu từ cấu hình đang lưu. Tài khoản có cấu hình mà form không hiển thị được thì giữ nguyên: form ghi kept as stored: this form cannot show it và chế độ VA ghi (kept as stored). VA đã ngừng hoạt động trong danh sách đang lưu cũng được giữ.

CLI chưa có flag bật gửi lại khi handler trả status ngoài 2xx. Bật bằng công tắc Tự động gửi lại khi server trả lỗi của webhook trên my.sepay.vn, hoặc bằng sepay api:

$ sepay api /webhooks/<webhook-xid> -X PUT -f 'retry_conditions={"non_2xx_status_code":1}'

Lỗi kết nối và hết thời gian chờ luôn được gửi lại, không cần bật.

webhook test

Kiểm tra handler trong script: lệnh tạo giao dịch sandbox, chờ thông báo, gửi vào handler một lần rồi thoát theo phản hồi của handler. Không cần chạy listen.

Production không có lệnh tương ứng; để thử endpoint trên production, dùng nút Gửi thử của webhook.

Tham số

FlagKiểuBắt buộcMô tả
--forwardstringCóĐịa chỉ handler
--amountintCóSố tiền VND, từ 1.000 đến 499.000.000
--expect-statusintKhôngHTTP status handler phải trả. Mặc định: mọi status 2xx
--eventstringKhôngpayment_in (mặc định), payment_out, va_credit
--timeoutdurationKhôngThời gian chờ. Mặc định 10s
--bank-accountstringKhôngXid tài khoản sandbox; bắt buộc trong script khi công ty có nhiều tài khoản
--vastringVới va_creditSố VA
--webhookstringKhôngWebhook dùng để gửi thử; chọn webhook có secret mà handler đang giữ khi nhiều webhook cùng áp dụng cho tài khoản
--forward-credentialsboolKhôngChuyển Authorization, X-Secret-Key tới handler không phải loopback; mặc định không chuyển

Ví dụ

$ sepay webhook test --forward localhost:3000/webhooks/sepay --amount 50000Fired payment_in event; waiting for the handler...✓ handler responded 200 in 12ms
Tình huốngExit code
Handler trả status 2xx (hoặc đúng --expect-status)0
Handler trả status khác, hoặc không trả lời6
Hết --timeout mà thông báo chưa về1
Sai flag2

Với --json, stdout là {"event", "status_code", "latency_ms", "ok"}; khi thất bại, ok là false và chi tiết in ra stderr. Script nên dựa vào exit code.

Lệnh chỉ so status, không đọc body. Khi gửi tới URL của webhook, SePay còn kiểm tra body theo yêu cầu phản hồi, nên handler đạt webhook test vẫn cần trả đúng body đó.

webhook logs

Liệt kê lịch sử gửi của webhook, mới nhất trước. Không truyền gì thì liệt kê của mọi webhook.

FlagKiểuMô tả
--statusstringsuccess, failed (kết quả gửi tới URL của webhook), listen (đã đẩy tới webhook listen), skipped (bị bộ lọc bỏ qua, không phải lỗi)
--sincestringChỉ log từ thời điểm này: khoảng thời gian (24h), ngày hoặc ngày giờ
--untilstringChỉ log tới ngày hoặc ngày giờ này; chỉ ghi ngày thì tính tới hết ngày đó
--webhookstringXid webhook; cũng nhận làm đối số
--transactionstringXid giao dịch, tức giá trị txn= mà webhook listen in ra
--page, --per-pageintPhân trang; tối đa 100 dòng mỗi trang
$ sepay webhook logs --status failed --since 24hDATE                 STATUS  CODE  REPLAY  TRANSACTION                           WEBHOOK                               URL2026-09-22 15:40:13  failed  500   no      a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98  5f0e2a7b-xxxx-xxxx-xxxx-fa163e2f7c98  https://api.congty.vn/webhooks/sepaypage 1/1 · 1 of 1

Mỗi lần gửi được xác định bằng cặp TRANSACTION và WEBHOOK. Truyền cả hai cho webhook replay để gửi lại.

webhook replay

Gửi lại một lần gửi trong lịch sử tới webhook đã nhận nó. Lần gửi được xác định bằng xid giao dịch và xid webhook, lấy từ cột TRANSACTION và WEBHOOK của webhook logs, hoặc từ txn= và wh= mà webhook listen in ra.

Tham sốKiểuBắt buộcMô tả
<transaction-xid> hoặc --transactionstringTrong scriptXid giao dịch của lần gửi
--webhookstringKhi giao dịch đã gửi tới nhiều webhookXid webhook đã nhận lần gửi
--forceboolKhôngGửi lại cả lần gửi handler đã nhận thành công (chỉ có tác dụng trên production)
$ sepay webhook replay <transaction-xid> --webhook <webhook-xid>✓ Replayed: handler answered 200 in 142ms.
  • Chỉ truyền xid giao dịch: giao dịch chỉ gửi tới một webhook thì CLI lấy luôn webhook đó. Gửi tới nhiều webhook thì CLI cho chọn trong terminal; trong script thì báo lỗi kèm danh sách xid webhook để bạn truyền --webhook.
  • Không truyền gì: trong terminal, CLI liệt kê 20 lần gửi gần nhất gửi lại được để chọn.
  • Handler không trả 2xx thì lệnh vẫn thành công và in ! Replayed, but the handler answered 500 (...). Không kết nối được handler thì in ! Replayed, but the handler could not be reached (...). Lần gửi lại tới được handler nhưng không có status trả về thì in ✓ Replayed. Với webhook nhận qua webhook listen, CLI in Replayed (delivered). Check the result with: sepay webhook logs --transaction <transaction-xid> --webhook <webhook-xid>.

Lần gửi lại đi tới URL của webhook nếu webhook có URL, đồng thời tạo bản sao mới về webhook listen đang mở. Lệnh luôn hỏi xác nhận. Trên sandbox, không có terminal thì cần --yes; trên production, lệnh theo luật xác nhận.

Gửi lại trên production

Trên production, lần gửi lại đi thẳng tới handler thật. Handler không chống trùng sẽ ghi nhận đơn hàng thêm một lần, nên trước khi hỏi xác nhận, CLI in giao dịch, số tiền, URL nhận và kết quả lần gửi gần nhất:

$ sepay webhook replay <transaction-xid> --webhook <webhook-xid> --env productionenv: productionTransaction  <transaction-xid>Amount       +120.000Sent to      https://api.congty.vn/webhooks/sepayLast result  failed · HTTP 500 · 2026-11-05 15:40:13! a handler that does not dedupe may credit this order twice! live: replay transaction <transaction-xid> to webhook <webhook-xid> targets PRODUCTION? replay transaction <transaction-xid> to webhook <webhook-xid> on production? [y/N]
  • Lần gửi mà handler đã nhận thành công thì SePay từ chối gửi lại (replay_already_delivered). Vẫn cần gửi thì thêm --force; CLI yêu cầu gõ lại mã giao dịch (Type <transaction-xid> to confirm). --yes không thay được bước gõ này, nên --force trên production chỉ chạy trong terminal.
  • SePay giới hạn số lần gửi lại mỗi giao dịch, tính chung mọi webhook của giao dịch đó. Chạm giới hạn thì lệnh báo replay_rate_limited kèm thời điểm chạy lại được.
  • Ngoài webhook:write, phần xem trước cần scope read để đọc giao dịch và lịch sử gửi.

Bạn cũng có thể phát lại bằng nút Phát lại trong lịch sử gửi webhook trên my.sepay.vn.

Thông báo lỗi

Thông báo hoặc trạng tháiNguyên nhân
this event would not be delivered: ... (webhook test)Không webhook nào khớp tài khoản và loại sự kiện, hoặc webhook bật --skip-if-no-code / --prefix-filter (giao dịch thử không có mã thanh toán). Tạo webhook nhận mọi tài khoản: sepay webhook create --listen-only --bank-mode all
handler returned 500, want 2xx (webhook test)Handler trả status khác mong đợi; dòng tiếp theo in body handler trả về
timed out waiting for the payment_in event (webhook test)Thông báo chưa về trong --timeout; tăng --timeout rồi chạy lại
failed trong webhook logs dù handler nhận đượcHandler không trả 200/201 kèm {"success": true}, hoặc trả lời chậm quá 30 giây (Xử lý lỗi)