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

# Webhooks Command

> Manage agent webhook primitives — view, deploy, activate, and subscribe to platform events

## Overview

`lua webhooks` manages HTTP webhook primitives defined with `LuaWebhook`. Each webhook is an addressable endpoint your agent exposes for external services (Stripe, Shopify, etc.) to call. The command also manages **event subscriptions** — wiring a webhook to platform events like `message.delivered`.

```bash theme={null}
lua webhooks                              # Interactive management
lua webhooks view                         # List all webhooks
lua webhooks list-events                  # See subscribable event types
lua webhooks subscribe --webhook-name paymentHook --event message.delivered
```

<Note>
  For defining webhooks in code, see [LuaWebhook API](/api/luawebhook).
</Note>

## Subcommands

| Action        | What it does                                               |
| ------------- | ---------------------------------------------------------- |
| `view`        | List all webhooks defined on the agent.                    |
| `versions`    | List every version of a webhook.                           |
| `deploy`      | Promote a version to active.                               |
| `activate`    | Re-enable a deactivated webhook.                           |
| `deactivate`  | Stop the webhook from receiving traffic. Version retained. |
| `delete`      | Permanently remove a webhook and all its versions.         |
| `list-events` | Print the catalog of subscribable platform events.         |
| `subscribe`   | Subscribe a webhook to a platform event.                   |
| `unsubscribe` | Remove a webhook's subscription to an event.               |

## Options

| Option                    | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| `--webhook-name <name>`   | Webhook name. Required for most non-interactive actions.             |
| `--webhook-version <ver>` | Version for `deploy`. Pass `latest` for the newest.                  |
| `--event <type>`          | Event type for `subscribe`/`unsubscribe` (e.g. `message.delivered`). |

## Examples

```bash theme={null}
# Interactive
lua webhooks

# List everything
lua webhooks view

# Promote a version
lua webhooks deploy --webhook-name paymentHook --webhook-version 1.0.3
lua webhooks deploy --webhook-name paymentHook --webhook-version latest

# Pause and resume
lua webhooks deactivate --webhook-name paymentHook
lua webhooks activate   --webhook-name paymentHook

# Delete
lua webhooks delete --webhook-name oldHook

# Event subscriptions
lua webhooks list-events
lua webhooks subscribe   --webhook-name paymentHook --event message.delivered
lua webhooks unsubscribe --webhook-name paymentHook --event message.delivered
```

## Webhooks vs Integration Triggers

Two different things, often confused:

| Concept                 | Source                                                                                                          | Manage with                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Webhook primitive**   | An HTTP endpoint **your agent owns** that external services call. Defined in code with `LuaWebhook`.            | `lua webhooks`                                                            |
| **Integration trigger** | A subscription on a third-party service (Linear, Discord, etc.) that calls into your agent on a specific event. | [`lua triggers`](/cli/integrations-command) / `lua integrations webhooks` |

Use `lua webhooks` for things like "Stripe will call this URL on `payment.succeeded`." Use `lua triggers` for things like "wake my agent when a Linear issue is created."

## Event Subscriptions

Some agent channels emit platform events your webhook can subscribe to — for example, `message.delivered` for WhatsApp delivery receipts. Run `lua webhooks list-events` to see the current catalog.

```bash theme={null}
lua webhooks list-events
```

Subscribe a webhook to an event so the webhook fires whenever the event occurs:

```bash theme={null}
lua webhooks subscribe --webhook-name deliveryTracker --event message.delivered
```

## Common Workflow

```bash theme={null}
# Edit your webhook in src/webhooks/payment.ts, then:
lua push webhook                              # Build + upload
lua webhooks versions --webhook-name payment  # Confirm version is on server
lua webhooks deploy --webhook-name payment --webhook-version latest
lua logs --type webhook --name payment --limit 20  # Verify traffic
```

## Related

* [LuaWebhook API](/api/luawebhook)
* [Integrations Command](/cli/integrations-command) — third-party triggers
* [Logs Command](/cli/logs-command)
* [Test Command](/cli/skill-management#lua-test) — `lua test webhook` for local testing