To receive SePay webhooks on the machine you code on, without setting up a tunnel or a public URL, run sepay webhook listen. It forwards every webhook delivery to your local handler, so you can test your webhook code before it goes to a server.
webhook listen runs on the sandbox only. You need to be signed in, your company needs Test Mode turned on (see Test Mode), a sandbox bank account and at least one active webhook. The quickest way is sepay sandbox init --with-webhook-listen, which creates the account and a webhook with no URL (sandbox init).
webhook listen doesn't run on production: the CLI exits with exit code 2 before calling the server, and the server also returns HTTP 404 This endpoint is only available in the sandbox environment to every listen call on production. The same goes for pg ipn listen and bankhub ipn listen. On production, look at each delivery and your webhook URL's response with webhook logs or the webhook delivery history on the Dashboard.
How forwarding works
listenreceives a copy of every delivery over a connection your machine opens to SePay, so you don't need a tunnel.- Your handler gets the same body and headers as the webhook URL, so signature checks behave as in production.
- Whatever your handler returns, delivery (1) is unaffected. A
--listen-onlywebhook has no URL, so only branch (2) applies.
The payload structure is in Webhook integration, and how to check the signature is in Webhook authentication.
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--forward | string | In scripts | Handler address: localhost:3000, localhost:3000/webhooks/sepay or http(s)://.... In a terminal, the CLI prompts if you omit it |
--print | bool | No | Print the full payload of every notification |
--events | string[] | No | Forward only these types: payment_in, payment_out (money into a virtual account is also payment_in) |
--webhook | string | No | Forward only deliveries of this webhook (xid). The CLI doesn't check the xid; a wrong xid just shows nothing |
--forward-retries | int | No | How many times the CLI resends a failed delivery (see Retries on your machine). Default 7, at most 10; 0 means a single attempt |
--headers | bool | No | Print the headers of the forwarded request |
--forward-credentials | bool | No | Pass Authorization and X-Secret-Key on to a non-loopback handler; not passed by default |
Run sepay webhook listen --help for the other flags (--skip-tls-verify for an https handler on your machine, --reconnect-max).
Example
$ 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= is the transaction xid; wh= is the xid of the webhook that was delivered. Press Ctrl+C to stop the command. The command also stops with exit code 4 when your sign-in session is revoked (access_revoked); run sepay login, then start listen again.
Notes
listengets notifications for every bank account in the company, VA credits (payment_in) included, as long as an active webhook applies to that account. Check withwebhook list --active 1;webhook get <xid>showsTargetandBank account.listengets only the first delivery of each transaction and re-deliveries fromwebhook replay. When SePay retries after the webhook URL fails, that retry doesn't pass throughlisten; look inwebhook logs.listenreceives copies for testing, so it can miss events when the connection is slow or drops, and a missed event isn't sent again. Delivery to your webhook URLs is unaffected; reconcile withsepay transaction list.- If several webhooks apply to the same account, or two
listenprocesses run at once, your handler receives several requests with the sameid. Deduplicate byid, or filter with--webhook. - The
idin the payload is an integer, not an xid, sotransaction getrejects it. Usetxn=, or look the transaction up byreferenceCode:sepay transaction list --reference-number <referenceCode>.
Retries on your machine
If your handler fails, listen resends on SePay's retry schedule: 7 times by default, up to 10 (spread over about 2.4 hours).
- Each retry resends the original bytes, signature and timestamp included. A handler that rejects old timestamps will reject the later retries.
- A non-2xx response is retried only when the webhook has
retry_conditions.non_2xx_status_codeturned on; a connection error or timeout is always retried. Turn it on with the Tự động gửi lại khi server trả lỗi (auto retry on server error) toggle on my.sepay.vn or withsepay api(how).listenreads that setting at startup, so restartlistenafter changing it. - Stop
listenand the retries still waiting are dropped; restarting doesn't resume them. If you run severallistenprocesses, they are dropped only when the lastlistenprocess stops. At most 500 deliveries (24 MiB) wait at once. - Retries run only with a handler on your machine (loopback). With a handler on another machine,
listendelivers once. - With several
listenprocesses on one handler, each delivers the first attempt and only one sends the retries. - In a terminal, type
retriesand press Enter to list pending retries;kill <n>orkill allcancels them, andretries off/retries onstops or resumes scheduling new ones.
Error messages
| Message or status | Cause |
|---|---|
not responding (is your handler running?) | Your handler isn't running, or it runs on a different port |
did not answer in time | Your handler took the request but didn't answer in time |
failed TLS verification (an untrusted or mismatched certificate) | --forward uses https and the handler's certificate isn't trusted or doesn't match the host name |
webhook listen is sandbox-only; drop --env production | listen runs on the sandbox only. Drop --env production; if your default environment is production, add --env sandbox. On production, look at deliveries with webhook logs |
Status 404 in the result line | Wrong path in --forward |