Skip to main content

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.

​
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. 
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
For defining webhooks in code, see LuaWebhook API.

​
Subcommands

ActionWhat it does
viewList all webhooks defined on the agent.
versionsList every version of a webhook.
deployPromote a version to active.
activateRe-enable a deactivated webhook.
deactivateStop the webhook from receiving traffic. Version retained.
deletePermanently remove a webhook and all its versions.
list-eventsPrint the catalog of subscribable platform events.
subscribeSubscribe a webhook to a platform event.
unsubscribeRemove a webhook’s subscription to an event.

​
Options

OptionDescription
--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

# 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:
ConceptSourceManage with
Webhook primitiveAn HTTP endpoint your agent owns that external services call. Defined in code with LuaWebhook.lua webhooks
Integration triggerA subscription on a third-party service (Linear, Discord, etc.) that calls into your agent on a specific event.lua triggers / 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. 
lua webhooks list-events
Subscribe a webhook to an event so the webhook fires whenever the event occurs: 
lua webhooks subscribe --webhook-name deliveryTracker --event message.delivered

​
Common Workflow

# 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