Manage via CLI

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

curl -fsSL https://keebai.ai/install.sh | bash

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

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

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

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

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]

Flag	Required	Description
`--url`	yes	HTTPS endpoint on your side.
`--event`	yes, repeatable	At least one. See the catalog.
`--name`	yes	Human-readable label to identify the subscription in listings.
`--header`	no, repeatable	Extra headers (`Name:Value` format). Useful for your own routing/auth.
`--inactive`	no	Creates 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

Flag	Description
`--api-url <url>`	Override the API base (default `https://api.keebai.com/v1`). Useful for staging.
`--output pretty\|json`	Output format. Use `json` for piping to `jq`.
`--verbose`	Logs every HTTP request. Never prints the full secret, only the first 12 chars.
`--no-browser`	In `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.

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 with a text message, which detects the channel type (Cloud API vs QR) and routes accordingly. Templates and bulk are not supported against QR channels.

Get started

Setup

Reference

Manage via CLI

Installation

Quickstart: 5 minutes to your first event

Available commands

`keebai webhooks new`

`keebai webhooks list`

`keebai webhooks test <id>`

`keebai webhooks deliveries <id>`

`keebai webhooks rotate <id>`

`keebai webhooks delete <id>`

Global flags

CI/CD

See also

Signature verification

Event catalog

REST endpoints

Connect WhatsApp via CLI

Connect WhatsApp via QR

Connect WhatsApp from the CLI

​Installation

​Quickstart: 5 minutes to your first event

​Available commands

​keebai webhooks new

​keebai webhooks list

​keebai webhooks test <id>

​keebai webhooks deliveries <id>

​keebai webhooks rotate <id>

​keebai webhooks delete <id>

​Global flags

​CI/CD

​See also

Signature verification

Event catalog

REST endpoints

Connect WhatsApp via CLI

Connect WhatsApp via QR

​Connect WhatsApp from the CLI

Installation

Quickstart: 5 minutes to your first event

Available commands

`keebai webhooks new`

`keebai webhooks list`

`keebai webhooks test <id>`

`keebai webhooks deliveries <id>`

`keebai webhooks rotate <id>`

`keebai webhooks delete <id>`

Global flags

CI/CD

See also

Connect WhatsApp from the CLI