The webhook group creates, edits and deletes webhooks, lists delivery history, re-sends a past delivery, and checks your handler with webhook test.
The commands run on both sandbox and production, except listen, create --listen-only and test, which run on the sandbox only. On production, create, update, delete and replay need the webhook:write scope and the other commands need read. You need to be signed in. On the sandbox, your company needs Test Mode turned on (see Test Mode) and a sandbox bank account (sandbox init).
To receive webhooks on the machine you code on, see Receive webhooks locally (webhook listen, sandbox only).
Commands
| Command | Description | Environment |
|---|---|---|
webhook create | Create a webhook | Both |
webhook listen | Forward webhooks to your own machine | Sandbox |
webhook test | Create a test transaction and check your handler's response | Sandbox |
webhook logs | Delivery history | Both |
webhook replay | Re-deliver a webhook | Both |
webhook update | Edit a webhook | Both |
webhook list, get <xid>, delete <xid> | View and delete webhooks | Both |
webhook list filters by status with --active 0 or --active 1. webhook delete asks for confirmation before deleting. On sandbox, without a terminal you need --yes; on production, the command follows the confirmation rule.
webhook create
Creates a webhook that delivers to your URL (--url), or one with no URL that you receive only through webhook listen (--listen-only, sandbox only).
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--bank-mode | string | In a script | single | multi | all: one, several or every bank account. In a terminal, the CLI asks when you leave it out |
--bank-account | string[] | With single, multi | Account xid; repeat the flag for several |
--bank-config | string[] | No | What each account notifies, as <xid>=<account number>:<VAs>. Repeat the flag for each account. See Choose what each account notifies |
--va-xid | string[] | With VA mode list | Xid of a VA to receive; repeat the flag for several |
--event-type | string | No | all | in | out. Defaults to all |
--url | string | Unless --listen-only | Your server's URL, reachable from the Internet; the domain must resolve on public DNS |
--listen-only | bool | No | No URL; receive only through webhook listen (sandbox only) |
--auth-type | string | No | none | apikey | hmac | oauth2 |
--secret | string | With apikey, hmac | Shared secret; - reads it from stdin so it stays out of your shell history |
--name | string | No | Webhook name |
For the other flags (--content-type, --only-va, --prefix-filter, --skip-if-no-code, --verify-payment, --oauth2-*), run sepay webhook create --help; what each webhook option does is in Create a webhook.
Examples
Create a webhook without a URL that only delivers through webhook listen:
$ sepay webhook create --listen-only --bank-mode all --event-type inCreate a webhook that delivers to your URL, signed with HMAC. The secret comes through stdin from the SECRET environment variable:
$ printf '%s' "$SECRET" | sepay webhook create --url https://api.example.com/webhooks/sepay \--bank-mode all --event-type in --auth-type hmac --secret -Create a webhook for an account that only receives money through VAs, receiving two of its VAs:
$ sepay webhook create --url https://api.example.com/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>The command prints ✓ Created webhook <xid>..
Create a webhook in a terminal
Run sepay webhook create in a terminal and the CLI asks for whatever you didn't pass as a flag, in this order:
- Delivery:
Send events to my URLorWatch events locally with "sepay webhook listen" (no URL). Asked on the sandbox only. - Webhook URL: an empty or invalid URL is asked again right away, instead of failing at SePay after every other question.
- Webhook name (optional).
- Authentication:
None,API key,HMAC signatureorOAuth2. A webhook received throughlistenhas noOAuth2. Secrets are typed without echo. - Targeting mode:
single,multiorall. - For
singleandmulti: pick the accounts, then choose what each one notifies in the What each bank account notifies form (next section).
The CLI doesn't ask for the event type; it defaults to all, and --event-type changes it. On production, the CLI prints ! live: create webhook targets PRODUCTION and asks for confirmation before creating. A create command has no id, so on production it runs only in a terminal; --yes can't confirm it.
Choose what each account notifies
Each account in a single or multi webhook has two choices, as in the webhook form on my.sepay.vn:
- Account number: transfers made straight to the account number.
- Virtual accounts:
All, including ones created later,Only selected(only the VAs you tick) orNone.
By default each account notifies both its account number and every VA. The form only offers what the account can notify; check which kind an account is in the Notifies row of sepay bank-account get <xid>:
| Account | In the form | Valid --bank-config |
|---|---|---|
| Receives through VAs only: MSB, KienLongBank, OCB, personal and business household BIDV, and Vietcombank accounts, only when connected over API with no SMS | Shows virtual accounts only; Account number is locked off. With no VA yet it shows virtual accounts only · none issued yet, so nothing is notified until one is | off:all, off:list |
| Receives on the account number and through VAs (most banks over API, any account connected over SMS) | Any choice | Any combination except off:none |
| Has no VAs | Shows no virtual accounts; account number only | on:none |
In the form, ↑/↓ move, Space toggles the current box, ←/→ change the VA mode and Enter finishes. Only selected is offered only when the account has at least one active VA; pick it and the account's VAs show right below it to tick. The CLI refuses Enter while any account would notify nothing, for example Only selected with no VA ticked, and prints the reason at the bottom of the form. Once accepted, each account leaves one summary line, for example account number + all virtual accounts.
In a script, use --bank-config instead of the form. The CLI checks it before sending and refuses a config the account can't take, with the reason, for example off:none, or list without any --va-xid of that account (va mode list needs at least one of this account's virtual accounts in --va-xid).
Sent straight through sepay api, SePay still checks it and answers 422 validation_error when a config would notify nothing, for example bank account <xid> would receive nothing: set receive_primary true or va_mode all or list or bank account <xid> only delivers virtual-account transactions; va_mode must be all or list.
webhook update
Changes a webhook. Only the flags you pass change; everything else is kept.
$ sepay webhook update <webhook-xid> --url https://api.example.com/webhooks/sepay-new$ sepay webhook update <webhook-xid> --event-type in --skip-if-no-codeChange one account's config; the other accounts keep theirs:
$ sepay webhook update <webhook-xid> --bank-config <bank-account-xid>=off:list --va-xid <va-xid>The command takes the same flags as webhook create. On the sandbox, --listen-only switches the webhook to delivering only through webhook listen; pass --url to move it back to your URL. Alias: webhook edit. Leave out <webhook-xid> and, in a terminal, the CLI lets you pick from your webhooks; in a script it is required.
Run sepay webhook update <webhook-xid> with no flags in a terminal and the CLI asks What do you want to edit?, listing each setting with its stored value: name, URL, event type, content type, payment verification, skipping events with no payment code, payment code prefixes, authentication and Targeting. Pick Targeting and the CLI asks for the mode and accounts again, then opens the Choose what each account notifies form, starting from the stored config. An account whose stored config the form can't show is kept as it is: the form notes kept as stored: this form cannot show it and labels its VA mode (kept as stored). Inactive VAs in a stored list are kept too.
The CLI has no flag yet to retry when the handler answers outside 2xx. Turn it on with the webhook's 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:
$ sepay api /webhooks/<webhook-xid> -X PUT -f 'retry_conditions={"non_2xx_status_code":1}'Connection failures and timeouts are always retried; nothing to turn on.
webhook test
Checks your handler from a script: the command creates a sandbox transaction, waits for the notification, delivers it to your handler once and exits according to the handler's response. You don't need to run listen.
Production has no equivalent command; to test an endpoint on production, use the webhook's Test send button.
Parameters
| Flag | Type | Required | Description |
|---|---|---|---|
--forward | string | Yes | Handler address |
--amount | int | Yes | Amount in VND, from 1,000 to 499,000,000 |
--expect-status | int | No | The HTTP status the handler must return. Default: any 2xx status |
--event | string | No | payment_in (default), payment_out, va_credit |
--timeout | duration | No | How long to wait. Default 10s |
--bank-account | string | No | Sandbox account xid; required in scripts when the company has several accounts |
--va | string | With va_credit | VA number |
--webhook | string | No | The webhook to use for the test delivery; when several webhooks apply to the account, pick the one whose secret your handler holds |
--forward-credentials | bool | No | Pass Authorization and X-Secret-Key to a non-loopback handler; they're withheld by default |
Example
$ sepay webhook test --forward localhost:3000/webhooks/sepay --amount 50000Fired payment_in event; waiting for the handler...✓ handler responded 200 in 12ms| Situation | Exit code |
|---|---|
The handler returns a 2xx status (or the --expect-status value) | 0 |
| The handler returns another status, or doesn't respond | 6 |
--timeout elapses before the notification arrives | 1 |
| Invalid flag | 2 |
With --json, stdout is {"event", "status_code", "latency_ms", "ok"}; on a failure ok is false and the details go to stderr. Scripts should rely on the exit code.
The command compares the status only and doesn't read the body. When delivering to the webhook URL, SePay also checks the body against the response requirements, so a handler that passes webhook test still needs to return that body.
webhook logs
Lists webhook delivery history, newest first. With no argument it lists every webhook's.
| Flag | Type | Description |
|---|---|---|
--status | string | success, failed (the result of delivery to the webhook URL), listen (pushed to webhook listen), skipped (skipped by a filter, not an error) |
--since | string | Only logs from this point: a duration (24h), a date or a datetime |
--until | string | Only logs up to this date or datetime; a bare date means the end of that day |
--webhook | string | Webhook xid; also accepted as the argument |
--transaction | string | Transaction xid, the txn= value webhook listen prints |
--page, --per-page | int | Pagination; at most 100 rows per page |
$ 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.example.com/webhooks/sepaypage 1/1 · 1 of 1A delivery is identified by its TRANSACTION and WEBHOOK pair. Pass both to webhook replay to re-send it.
webhook replay
Re-sends one logged delivery to the webhook that received it. The delivery is identified by the transaction xid and the webhook xid, from the TRANSACTION and WEBHOOK columns of webhook logs, or from the txn= and wh= values webhook listen prints.
| Parameter | Type | Required | Description |
|---|---|---|---|
<transaction-xid> or --transaction | string | In a script | Transaction xid of the delivery |
--webhook | string | When the transaction went to several webhooks | Xid of the webhook that received it |
--force | bool | No | Re-send a delivery your handler already acknowledged (only matters on production) |
$ sepay webhook replay <transaction-xid> --webhook <webhook-xid>✓ Replayed: handler answered 200 in 142ms.- Only a transaction xid: if the transaction went to one webhook, the CLI takes that webhook. If it went to several, the CLI lets you pick in a terminal; in a script it fails with the list of webhook xids to pass as
--webhook. - Nothing: in a terminal, the CLI lists the 20 most recent replayable deliveries to pick from.
- If the handler doesn't answer 2xx, the command still succeeds and prints
! Replayed, but the handler answered 500 (...). If the handler can't be reached, it prints! Replayed, but the handler could not be reached (...). A replay that got through with no status code to show prints✓ Replayed.For a webhook received throughwebhook listen, the CLI printsReplayed (delivered). Check the result with: sepay webhook logs --transaction <transaction-xid> --webhook <webhook-xid>.
The re-delivery goes to the webhook URL if the webhook has one, and also creates a new copy for any open webhook listen. The command always asks for confirmation. On sandbox, without a terminal you need --yes; on production, the command follows the confirmation rule.
Replay on production
On production, a replay goes straight to your live handler. A handler that doesn't dedupe credits the order a second time, so before the confirm the CLI shows the transaction, its amount, the receiving URL and the last result:
$ 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]- SePay refuses to re-send a delivery your handler already acknowledged (
replay_already_delivered). If you still need it, add--force; the CLI then asks you to type the transaction id back (Type <transaction-xid> to confirm).--yesdoesn't answer that step, so--forceon production only runs in a terminal. - SePay caps how many times one transaction is replayed, counted across all its webhooks. Past the cap the command fails with
replay_rate_limitedand says when you can run it again. - Besides
webhook:write, the preview needs thereadscope to read the transaction and its delivery log.
You can also replay from the Replay button in the webhook delivery history on my.sepay.vn.
Error messages
| Message or status | Cause |
|---|---|
this event would not be delivered: ... (webhook test) | No webhook matches the account and event type, or the webhook uses --skip-if-no-code / --prefix-filter (a test transaction has no payment code). Create one that covers every account: sepay webhook create --listen-only --bank-mode all |
handler returned 500, want 2xx (webhook test) | Your handler returned a different status; the next line prints the body it sent |
timed out waiting for the payment_in event (webhook test) | The event didn't arrive within --timeout; raise --timeout and run it again |
failed in webhook logs even though the handler received the request | The handler didn't return 200/201 with {"success": true}, or took more than 30 seconds to respond (Error handling) |