> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # lua webhooks > List, deploy, activate, deactivate, and delete webhooks, and manage their event subscriptions `lua webhooks` manages the [webhooks](/concepts/webhooks) defined with `LuaWebhook` and pushed with `lua push webhook`: it lists them, makes a pushed version live, turns a webhook on or off, deletes it, and subscribes it to platform events. Every action runs against production and takes effect for the next request. *Verified against lua-cli 3.33.0.* ## Synopsis ```bash theme={null} lua webhooks [view|versions|deploy|activate|deactivate|delete|list-events|subscribe|unsubscribe] [--webhook-name ] [--webhook-version |latest] [--event ] ``` ## Description With no action the command opens a menu covering `view`, `versions`, `deploy`, `activate`, `deactivate`, and `delete`. `list-events`, `subscribe`, and `unsubscribe` exist only as arguments. `view` lists every webhook in `lua.skill.yaml` with its ID, whether a version is deployed, and when. It does not print the webhook's URL. `versions` prints a pointer to [`lua version list`](/reference/cli/version): per-primitive history is managed by [agent versions](/concepts/releases-and-versions). `deploy` makes one pushed version live without a confirmation prompt. It is the same operation as `lua deploy webhook --name --set-version --force`; [`lua deploy`](/reference/cli/deploy) also records the deployed version in `lua.skill.yaml` and reports the agent version it promoted. `activate` and `deactivate` turn the webhook on or off without changing its version. A deactivated webhook stops receiving requests until you activate it again. `delete` removes the webhook from the server. A webhook that has pushed versions is deactivated instead of deleted and stays in `lua.skill.yaml` until you remove it. `delete` also resolves webhooks that exist only on the server. `list-events` prints the platform events a webhook can subscribe to. The catalog is fixed by the installed CLI: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.played`. `subscribe` adds one event to the webhook's subscriptions on the server and `unsubscribe` removes it; both are no-ops with exit `0` when the subscription is already in the requested state, and both refuse an event outside the catalog. What each event carries is described in [About webhooks](/concepts/webhooks). `--webhook-name` matches the name or the ID. Every form needs a project directory and a credential. ## Arguments | Argument | Values | Description | | -------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- | | `action` | `view`, `versions`, `deploy`, `activate`, `deactivate`, `delete`, `list-events`, `subscribe`, `unsubscribe` | Omit it to open the menu. | Accepted spellings: `show`, `info` → `view`; `list-versions`, `history` → `versions`; `publish` → `deploy`; `on`, `enable` → `activate`; `off`, `disable` → `deactivate`; `rm`, `remove`, `del` → `delete`; `events`, `list_events` → `list-events`; `sub` → `subscribe`; `unsub` → `unsubscribe`. ## Options | Option | Description | Default | | ------------------------- | ------------------------------------------------------------------------------------- | ------- | | `--webhook-name ` | Webhook name or ID. Required for every action except `view` and `list-events`. | — | | `--webhook-version ` | Version to deploy, or `latest` for the newest pushed version. Required for `deploy`. | — | | `--event ` | Event type for `subscribe` and `unsubscribe`; one of the values `list-events` prints. | — | | `--ci` | Global flag. Refuse any prompt with exit `1` instead of waiting for input. | off | ## Examples List the webhooks and whether each is deployed. ```bash theme={null} lua webhooks view ``` ```text Output theme={null} ============================================================ ⚙️ Production Webhooks ============================================================ 🪝 ticket-status-webhook Webhook ID: 1801aee9-5b6d-41e8-bbb8-dca0d11c3e5f Deployed ⭐ Deployed: 12/09/2026, 13:49:45 ============================================================ ``` Print the events a webhook can subscribe to. ```bash theme={null} lua webhooks list-events ``` ```text Output theme={null} ============================================================ 📡 Available event types ============================================================ • message.received • message.sent • message.delivered • message.read • message.failed • message.played ============================================================ Subscribe a webhook to an event: lua webhooks subscribe --webhook-name --event ``` Subscribe a webhook to delivery receipts from CI. ```bash theme={null} lua webhooks subscribe --webhook-name ticket-status-webhook --event message.delivered --ci ``` Make the newest pushed version live from CI. ```bash theme={null} lua webhooks deploy --webhook-name ticket-status-webhook --webhook-version latest --ci ``` Stop a webhook from receiving requests without deleting it. ```bash theme={null} lua webhooks deactivate --webhook-name ticket-status-webhook --ci ``` ## Exit codes | Code | Meaning | When | | ---- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | OK | The action completed, including a `subscribe` that was already in place or a `delete` that deactivated instead. | | `1` | Error | The server refused the change, `--webhook-version` names a version that does not exist, `--event` is outside the catalog, the webhook is missing on the server for `subscribe`, or a prompt was needed under `--ci`. | | `2` | Usage | Unknown action, or a required `--webhook-name`, `--webhook-version`, or `--event` is missing. | | `3` | Not found | The webhook is not in `lua.skill.yaml` (nor on the server, for `delete`), or it has no pushed versions to deploy. | | `9` | Auth | No valid credential. | | `10` | Forbidden | The credential cannot manage this agent. | | `11` | Unavailable | Network error or a server 5xx. | The full table is in [Errors and exit codes](/reference/cli/errors-and-exit-codes). ## See also * [`LuaWebhook`](/reference/sdk/luawebhook) — define a webhook, including its signing secret * [Handle a webhook](/build/handle-a-webhook) * [`lua triggers`](/reference/cli/triggers) — paste-anywhere URLs that wake the agent * [`lua integrations`](/reference/cli/integrations) — integration webhooks from connected SaaS * [`lua logs`](/reference/cli/logs) — `--type webhook --name `