Manage webhooks with SePay CLI

Create, update and delete SePay webhooks with SePay CLI, choose which accounts and VAs notify, read delivery logs, test your handler and replay deliveries.

||

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

CommandDescriptionEnvironment
webhook createCreate a webhookBoth
webhook listenForward webhooks to your own machineSandbox
webhook testCreate a test transaction and check your handler's responseSandbox
webhook logsDelivery historyBoth
webhook replayRe-deliver a webhookBoth
webhook updateEdit a webhookBoth
webhook list, get <xid>, delete <xid>View and delete webhooksBoth

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

FlagTypeRequiredDescription
--bank-modestringIn a scriptsingle | multi | all: one, several or every bank account. In a terminal, the CLI asks when you leave it out
--bank-accountstring[]With single, multiAccount xid; repeat the flag for several
--bank-configstring[]NoWhat each account notifies, as <xid>=<account number>:<VAs>. Repeat the flag for each account. See Choose what each account notifies
--va-xidstring[]With VA mode listXid of a VA to receive; repeat the flag for several
--event-typestringNoall | in | out. Defaults to all
--urlstringUnless --listen-onlyYour server's URL, reachable from the Internet; the domain must resolve on public DNS
--listen-onlyboolNoNo URL; receive only through webhook listen (sandbox only)
--auth-typestringNonone | apikey | hmac | oauth2
--secretstringWith apikey, hmacShared secret; - reads it from stdin so it stays out of your shell history
--namestringNoWebhook 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 in

Create 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:

  1. Delivery: Send events to my URL or Watch events locally with "sepay webhook listen" (no URL). Asked on the sandbox only.
  2. Webhook URL: an empty or invalid URL is asked again right away, instead of failing at SePay after every other question.
  3. Webhook name (optional).
  4. Authentication: None, API key, HMAC signature or OAuth2. A webhook received through listen has no OAuth2. Secrets are typed without echo.
  5. Targeting mode: single, multi or all.
  6. For single and multi: 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) or None.

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>:

AccountIn the formValid --bank-config
Receives through VAs only: MSB, KienLongBank, OCB, personal and business household BIDV, and Vietcombank accounts, only when connected over API with no SMSShows 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 isoff:all, off:list
Receives on the account number and through VAs (most banks over API, any account connected over SMS)Any choiceAny combination except off:none
Has no VAsShows no virtual accounts; account number onlyon: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-code

Change 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

FlagTypeRequiredDescription
--forwardstringYesHandler address
--amountintYesAmount in VND, from 1,000 to 499,000,000
--expect-statusintNoThe HTTP status the handler must return. Default: any 2xx status
--eventstringNopayment_in (default), payment_out, va_credit
--timeoutdurationNoHow long to wait. Default 10s
--bank-accountstringNoSandbox account xid; required in scripts when the company has several accounts
--vastringWith va_creditVA number
--webhookstringNoThe webhook to use for the test delivery; when several webhooks apply to the account, pick the one whose secret your handler holds
--forward-credentialsboolNoPass 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
SituationExit code
The handler returns a 2xx status (or the --expect-status value)0
The handler returns another status, or doesn't respond6
--timeout elapses before the notification arrives1
Invalid flag2

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.

FlagTypeDescription
--statusstringsuccess, failed (the result of delivery to the webhook URL), listen (pushed to webhook listen), skipped (skipped by a filter, not an error)
--sincestringOnly logs from this point: a duration (24h), a date or a datetime
--untilstringOnly logs up to this date or datetime; a bare date means the end of that day
--webhookstringWebhook xid; also accepted as the argument
--transactionstringTransaction xid, the txn= value webhook listen prints
--page, --per-pageintPagination; 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 1

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

ParameterTypeRequiredDescription
<transaction-xid> or --transactionstringIn a scriptTransaction xid of the delivery
--webhookstringWhen the transaction went to several webhooksXid of the webhook that received it
--forceboolNoRe-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 through webhook listen, the CLI prints Replayed (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). --yes doesn't answer that step, so --force on 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_limited and says when you can run it again.
  • Besides webhook:write, the preview needs the read scope 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 statusCause
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 requestThe handler didn't return 200/201 with {"success": true}, or took more than 30 seconds to respond (Error handling)