Skip to main content

CLI Reference

All webhook commands are under bankr webhooks.

Setup​

bankr webhooks init​

Scaffolds the webhooks/ directory and bankr.webhooks.json config file in the current directory.

bankr webhooks init

bankr webhooks add <name>​

Creates a new webhook handler at webhooks/<name>/index.ts with a starter template, and adds it to the config.

bankr webhooks add daily-summary
bankr webhooks add release-bot --provider github
FlagDescription
--provider <name>One of slack, github, stripe, generic (default). Non-generic providers include a signature verifier inline.
Webhook Name Rules

Names must be alphanumeric, hyphens, or underscores — max 47 characters. Examples: daily-summary, release_bot, stripe-listener.

When you answer "yes" to "Will this webhook use npm packages?", a package.json is scaffolded into the webhook's folder.

Deployment​

bankr webhooks deploy [name]​

Bundles and deploys your webhooks. If no name is given, deploys all webhooks in webhooks/.

bankr webhooks deploy                 # Deploy all
bankr webhooks deploy daily-summary   # Deploy one

The CLI:

  1. Reads your TypeScript handler source and optional package.json
  2. Sends them to Bankr for server-side bundling and sandboxing
  3. Registers the webhook and makes it live at https://webhooks.bankr.bot/u/<wallet>/<name>
Per-webhook permissions

The readOnly, allowedRecipients, rateLimit, maxPayloadBytes, and allowedIps fields in bankr.webhooks.json are applied to the deployed webhook. Redeploy after editing, or use the dashboard for live updates.

Management​

bankr webhooks list​

Shows your deployed webhooks with status, version, mode (read-only vs writes), and invocation count.

bankr webhooks list

bankr webhooks pause <name>​

Temporarily stop serving requests. Paused webhooks return 404 to callers until resumed.

bankr webhooks pause daily-summary

bankr webhooks resume <name>​

Resume a paused webhook.

bankr webhooks resume daily-summary

bankr webhooks delete <name>​

Permanently delete a webhook. Asks for confirmation before proceeding.

bankr webhooks delete daily-summary

bankr webhooks logs <name>​

Show the last 25 invocations for a webhook — timestamp, method, status, duration, the agent job ID when a prompt ran, and any error.

bankr webhooks logs daily-summary

Environment Variables​

bankr webhooks env set KEY=VALUE​

Sets an encrypted environment variable, available as process.env.KEY in all your webhook handlers.

bankr webhooks env set SLACK_SIGNING_SECRET=your-signing-secret
bankr webhooks env set GITHUB_WEBHOOK_SECRET=whsec_...
Key Validation

Keys must match ^[A-Za-z_][A-Za-z0-9_]{0,127}$. Keys with a reserved prefix such as BANKR_ are rejected to avoid conflicts with the runtime. Each value is capped at 4 KB.

Env vars are shared across all of your webhooks (and kept separate from your x402 env vars) — once set, any handler can read them via process.env. See Security for how they're stored.

bankr webhooks env list​

Lists environment variable names (values are never shown).

bankr webhooks env list
# Output:
#   SLACK_SIGNING_SECRET
#   GITHUB_WEBHOOK_SECRET

bankr webhooks env unset KEY​

Removes an environment variable. Takes effect on the next invocation.

bankr webhooks env unset GITHUB_WEBHOOK_SECRET

Config File​

See Config File for the full bankr.webhooks.json reference.