Receive webhooks locally with SePay CLI

Receive SePay sandbox webhooks in a handler on localhost with sepay webhook listen, no tunnel or public URL needed, with retries when the handler fails.

||

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

On production

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

How webhooks reach your machine
Rendering diagram...
  • listen receives 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-only webhook 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

FlagTypeRequiredDescription
--forwardstringIn scriptsHandler address: localhost:3000, localhost:3000/webhooks/sepay or http(s)://.... In a terminal, the CLI prompts if you omit it
--printboolNoPrint the full payload of every notification
--eventsstring[]NoForward only these types: payment_in, payment_out (money into a virtual account is also payment_in)
--webhookstringNoForward only deliveries of this webhook (xid). The CLI doesn't check the xid; a wrong xid just shows nothing
--forward-retriesintNoHow many times the CLI resends a failed delivery (see Retries on your machine). Default 7, at most 10; 0 means a single attempt
--headersboolNoPrint the headers of the forwarded request
--forward-credentialsboolNoPass 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

  • listen gets notifications for every bank account in the company, VA credits (payment_in) included, as long as an active webhook applies to that account. Check with webhook list --active 1; webhook get <xid> shows Target and Bank account.
  • listen gets only the first delivery of each transaction and re-deliveries from webhook replay. When SePay retries after the webhook URL fails, that retry doesn't pass through listen; look in webhook logs.
  • listen receives 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 with sepay transaction list.
  • If several webhooks apply to the same account, or two listen processes run at once, your handler receives several requests with the same id. Deduplicate by id, or filter with --webhook.
  • The id in the payload is an integer, not an xid, so transaction get rejects it. Use txn=, or look the transaction up by referenceCode: 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_code turned 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 with sepay api (how). listen reads that setting at startup, so restart listen after changing it.
  • Stop listen and the retries still waiting are dropped; restarting doesn't resume them. If you run several listen processes, they are dropped only when the last listen process 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, listen delivers once.
  • With several listen processes on one handler, each delivers the first attempt and only one sends the retries.
  • In a terminal, type retries and press Enter to list pending retries; kill <n> or kill all cancels them, and retries off / retries on stops or resumes scheduling new ones.

Error messages

Message or statusCause
not responding (is your handler running?)Your handler isn't running, or it runs on a different port
did not answer in timeYour 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 productionlisten 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 lineWrong path in --forward

Next

  • Webhooks: create and update webhooks, test your handler with webhook test and replay with webhook replay
  • Sandbox: simulate a transaction so a webhook gets delivered