Skip to main content
The keebai CLI is the fastest way to manage outbound webhooks from your terminal. Under the hood it uses the same /v1/webhooks endpoints as the API, with UX tuned for interactive workflows.

​
Installation

npm install -g @keebai/cli
After installing: 
keebai --version
keebai login           # device-flow authentication against the portal
keebai whoami          # confirms user/company/scopes

​
Quickstart: 5 minutes to your first event

1

Log in

keebai login
Opens the browser, prompts you to approve the device in the portal, and returns to the CLI with a PAT stored in ~/.keebai/credentials.json (chmod 600).
2

Create a subscription

keebai webhooks new \
  --url https://hooks.example.com/keebai \
  --event whatsapp.message.received \
  --event whatsapp.channel.connected \
  --name "Production CRM"
Output:
✓ Webhook created.
Created webhook wh_01HXYZ...
name:   Production CRM
url:    https://hooks.example.com/keebai
events: whatsapp.message.received, whatsapp.channel.connected
active: true

⚠ SECRET (shown once — copy it now, you cannot retrieve it later):
  whsec_8f2c5b3a9d4e7c1f...
Copy the whsec_xxx now. It can’t be retrieved later. If you lose it, you have to rotate it (which invalidates the old one).
3

Validate with a synthetic event

keebai webhooks test wh_01HXYZ... --event whatsapp.message.received
We send a synthetic envelope (with data._test: true) to your URL. If your endpoint verifies the signature and returns 2xx, you’ll see:
keebai webhooks deliveries wh_01HXYZ...
# status: success, status_code: 200, duration_ms: 142
4

Validate with real traffic

Send a WhatsApp message to your channel’s number. Your endpoint should receive a whatsapp.message.received with a shape compatible with the Meta Cloud API.

​
Available commands

​
keebai webhooks new

keebai webhooks new \
  --url <https://...> \
  --event <event_type> [--event <event_type>...] \
  --name <label> \
  [--header "Name:Value"] [--header ...] \
  [--inactive]
FlagRequiredDescription
--urlyesHTTPS endpoint on your side.
--eventyes, repeatableAt least one. See the catalog.
--nameyesHuman-readable label to identify the subscription in listings.
--headerno, repeatableExtra headers (Name:Value format). Useful for your own routing/auth.
--inactivenoCreates the subscription with is_active: false. Handy if you want to enable it later.
Prints the secret only once. Save it immediately.

​
keebai webhooks list

keebai webhooks list
keebai webhooks list --output json | jq

​
keebai webhooks test <id>

Dispatches a synthetic event (data._test: true) to the configured endpoint. 
keebai webhooks test wh_01HXYZ... --event whatsapp.message.received
Useful for validating your pipeline without real traffic. It arrives with the same HMAC signature as a real event.

​
keebai webhooks deliveries <id>

History of recent delivery attempts. 
keebai webhooks deliveries wh_01HXYZ... [--limit 50]
For each delivery, output shows: event_id, event_type, status (pending / success / failed / dead), status_code, attempts, duration_ms, last_error.

​
keebai webhooks rotate <id>

Generates a new secret. The old one is invalidated immediately. Asks for confirmation. 
keebai webhooks rotate wh_01HXYZ...
The new secret is shown the same way as in new. For zero-downtime rotation, see the strategy in security.

​
keebai webhooks delete <id>

Deletes the subscription. Future events are not sent. Asks for confirmation. 
keebai webhooks delete wh_01HXYZ...

​
Global flags

FlagDescription
--api-url <url>Override the API base (default https://api.keebai.com/v1). Useful for staging.
--output pretty|jsonOutput format. Use json for piping to jq.
--verboseLogs every HTTP request. Never prints the full secret, only the first 12 chars.
--no-browserIn keebai login, doesn’t open the browser; prints the URL to copy/paste. Useful over SSH/CI.
--profile <name>Multi-profile. Default default. Each profile stores separate credentials in ~/.keebai/credentials.json.

​
CI/CD

For pipeline use, override the token via env and skip the credentials file: 
export KEEBAI_API_TOKEN=kbai_pk_xxx
keebai webhooks list
KEEBAI_API_TOKEN takes precedence over ~/.keebai/credentials.json. The PAT must have the webhooks:read and/or webhooks:manage scopes depending on the commands you intend to run.

​
See also

Signature verification

How to validate X-Keebai-Signature in your endpoint.

Event catalog

Full list of types and data shapes.

REST endpoints

Same operations over HTTP, no CLI required.

Connect WhatsApp via CLI

keebai whatsapp connect and the equivalent API.

Connect WhatsApp via QR

keebai whatsapp connect --qr — QR pairing scanned straight from the terminal.

​
Connect WhatsApp from the CLI

There are two pairing modes: 
# Embedded Signup (Cloud API, opens browser):
keebai whatsapp connect [--coexistence] [--pipeline-id pip_…]

# QR multi-device (scan the QR in the terminal):
keebai whatsapp connect --qr [--name "WhatsApp Support"]
The --qr mode draws the code in your terminal, refreshes it automatically, and once scanned prints the channel_id of the new channel. SSE flow details in POST /v1/channels/whatsapp/connect (QR mode). Once a channel is connected (either Cloud API or QR), send messages with the same command: 
keebai whatsapp messages send \
  --from <channel_id-or-number> \
  --to +5491155555555 \
  --text "Hello from the QR channel"
Internally the CLI calls POST /v1/messages/text, which detects the channel type (Cloud API vs QR) and routes accordingly. Templates and bulk are not supported against QR channels.