LuaWebhook - Lua CLI

Overview

LuaWebhook allows you to create HTTP endpoints that can receive events from external services like Stripe, Shopify, GitHub, or any other webhook-enabled platform.

import { LuaWebhook, User } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle Stripe payment events',
  execute: async (event) => {
    const { body } = event;

    // ⚠️ Webhooks have NO conversational context
    // MUST provide userId to notify users
    
    if (body?.type === 'payment_intent.succeeded') {
      const customerId = body.data?.object?.metadata?.customerId;
      if (customerId) {
        const user = await User.get(customerId);
        await user.send([{
          type: 'text',
          text: '✅ Payment confirmed!'
        }]);
      }
    }
    return { received: true };
  }
});

export default paymentWebhook;

No Conversational Context: Webhooks execute outside of user conversations. You MUST use User.get(userId) with an explicit userId. Always store the user ID in your payment/order metadata.

HTTP webhooks for external integrations. Use with LuaAgent.

Webhooks vs Triggers

A LuaWebhook gives you an execute function and full control of the HTTP response — your code does the work. A LuaTrigger has no execute function: it declaratively verifies, filters, and transforms an incoming event, then wakes the agent to do the work itself. If the right reaction to an event is “have the agent handle it”, reach for a trigger; if you need a custom response body or code-only side effects, stay here. See LuaTrigger for the full comparison.

Use Cases

Payment Events

Stripe, PayPal webhooks for payment processing

E-commerce Updates

Shopify, WooCommerce order notifications

Git Events

GitHub, GitLab deployment triggers

Custom Integrations

Any service that sends HTTP webhooks

User Access in Webhooks

Context	How to Get User	userId Required?
Webhooks	`User.get(userId)`	✅ YES - Store in metadata
Tools	`User.get()`	❌ No - automatic context
LuaJob	`User.get(userId)`	✅ YES - Store in metadata
Jobs API	`jobInstance.user()`	❌ No - automatic context

Webhooks are context-less: They’re triggered by external systems, not user conversations. Always store the Lua user ID in your payment/order metadata so you can notify the right user.

Constructor

new LuaWebhook(config)

Creates a new webhook endpoint.

LuaWebhookConfig

required

Webhook configuration object

Configuration Parameters

Required Fields

string

required

Unique webhook nameFormat: lowercase, hyphens, underscoresExamples: 'payment-webhook', 'order-update-webhook'

function

required

Function that handles incoming webhook eventsSignature: (event: WebhookEvent) => Promise<any>

execute: async (event) => {
  const { query, headers, body } = event;
  // ...
}

Optional Fields

string

Webhook description for documentation

string

HMAC-SHA256 signing key. When set, every request must carry x-lua-signature: sha256=<hex HMAC-SHA256 of the raw body> or it is rejected with 401 before execute runs. Must be a literal or a build-time-resolvable constant. Rotate by changing the value and re-deploying; set to '' to turn verification off. See Verify Requests.

WebhookEvent Shape

Every webhook receives a single object with request details:

interface WebhookEvent {
  query: Record<string, any>;
  headers: Record<string, any>;
  body: any;
  timestamp: string;
  execution?: {
    eventId: string;      // stable idempotency key — survives retries & redeliveries
    executionId: string;  // unique per attempt
    attempt: number;      // 1-based attempt counter
  };
}

Destructure the pieces you need inside your handler:
const { query, headers, body, timestamp } = event;

execution is present only when your handler is invoked via a durably-delivered platform event. It is undefined for synchronous requests sent directly to your webhook URL and during local lua test / lua dev runs. See Delivery Semantics.

Complete Examples

Stripe Payment Webhook

import { LuaWebhook, env, Orders, User } from 'lua-cli';

const stripeWebhook = new LuaWebhook({
  name: 'stripe-payment-webhook',
  description: 'Handle Stripe payment events',
  
  execute: async (event) => {
    const { body } = event;
    console.log('Stripe event:', body?.type);
    
    switch (body?.type) {
      case 'payment_intent.succeeded':
        const paymentIntent = body.data?.object;
        
        // Update order status
        const order = await Orders.getById(paymentIntent.metadata.orderId);
        if (order) {
          await order.updateStatus('CONFIRMED');
          
          // Get user by ID from payment metadata
          const customerId = paymentIntent.metadata.customerId;
          const user = await User.get(customerId);
          
          // Notify the specific user
          await user.send([{
            type: 'text',
            text: `✅ Payment confirmed! Order #${order.id} is being processed. Amount: $${paymentIntent.amount/100}`
          }]);
        }
        
        return { success: true, orderId: order?.id };
        
      case 'payment_intent.payment_failed':
        const failed = body.data?.object;
        console.error('Payment failed:', failed);
        
        // Notify user of failure
        const failedCustomerId = failed.metadata.customerId;
        if (failedCustomerId) {
          const user = await User.get(failedCustomerId);
          await user.send([{
            type: 'text',
            text: `❌ Payment failed: ${failed.last_payment_error?.message}. Please try again.`
          }]);
        }
        
        return { success: false, reason: failed.last_payment_error?.message };
        
      default:
        console.log('Unhandled event type:', body?.type);
        return { received: true };
    }
  }
});

export default stripeWebhook;

Important: Always store the user ID (customerId) in your payment metadata so webhooks can notify the correct user. Example: metadata: { customerId: user.id, orderId: order.id }

Shopify Order Webhook

import { LuaWebhook, env, Data, User } from 'lua-cli';

const shopifyOrderWebhook = new LuaWebhook({
  name: 'shopify-order-webhook',
  description: 'Handle Shopify order events',
  
  execute: async (event) => {
    const { body } = event;
    const order = body;
    
    // Store order in custom data
    await Data.create('shopify-orders', {
      orderId: order.id,
      orderNumber: order.order_number,
      customer: order.customer,
      total: order.total_price,
      items: order.line_items,
      status: order.financial_status,
      customerId: order.customer.id,  // Store customer ID
      createdAt: order.created_at
    }, `Order #${order.order_number} ${order.customer.email} ${order.total_price}`);
    
    // Notify specific customer using their ID
    const user = await User.get(order.customer.id);
    await user.send([{
      type: 'text',
      text: `🛍️ Order #${order.order_number} confirmed!\n\nTotal: $${order.total_price}\nItems: ${order.line_items.length}\n\nWe'll send shipping updates soon!`
    }]);
    
    return {
      success: true,
      orderId: order.id,
      orderNumber: order.order_number,
      customerId: order.customer.id
    };
  }
});

export default shopifyOrderWebhook;

Customer Identification: Map external customer IDs (Shopify, Stripe) to Lua user IDs. Store this mapping in your order/payment metadata for webhook notifications.

GitHub Deployment Webhook

import { LuaWebhook, env, User } from 'lua-cli';

const githubWebhook = new LuaWebhook({
  name: 'github-deployment-webhook',
  description: 'Track GitHub deployment events',
  
  execute: async (event) => {
    const { body } = event;
    const payload = body;
    
    if (payload?.action === 'deployment_status') {
      const status = payload.deployment_status;
      const deployment = payload.deployment;
      
      // Notify on deployment completion
      // Note: You need to provide userId - webhooks have no conversational context
      if (status.state === 'success') {
        // In a real scenario, you'd get userId from deployment metadata
        // const user = await User.get(userId);
        // await user.send([{
        //   type: 'text',
        //   text: `🚀 Deployment successful!\n\nEnvironment: ${deployment.environment}\nRef: ${deployment.ref}\nURL: ${status.target_url}`
        // }]);
        console.log('Deployment successful:', deployment.environment);
      } else if (status.state === 'failure') {
        console.error('Deployment failed:', deployment.environment);
      }
      
      return { success: true, state: status.state };
    }
    
    return { received: true };
  }
});

export default githubWebhook;

Generic Webhook Template

import { LuaWebhook, env } from 'lua-cli';

const genericWebhook = new LuaWebhook({
  name: 'custom-integration-webhook',
  description: 'Handle events from custom service',
  
  execute: async (event) => {
    const { query, headers, body } = event;
    try {
      // Validate event structure
      if (!body || !body.type) {
        throw new Error('Invalid event structure');
      }
      
      // Log event for debugging
      console.log('Received webhook:', {
        type: body.type,
        timestamp: new Date().toISOString(),
        dataKeys: Object.keys(body.data || {})
      });
      
      // Process event based on type
      switch (body.type) {
        case 'resource.created':
          await handleCreate(body.data);
          break;
          
        case 'resource.updated':
          await handleUpdate(body.data);
          break;
          
        case 'resource.deleted':
          await handleDelete(body.data);
          break;
          
        default:
          console.log('Unknown event type:', body.type);
      }
      
      return { success: true, processed: body.type };
      
    } catch (error) {
      console.error('Webhook processing error:', error);
      
      return {
        success: false,
        error: error.message,
        timestamp: new Date().toISOString()
      };
    }
  }
});

async function handleCreate(data: any) {
  // Handle creation logic
  console.log('Resource created:', data.id);
}

async function handleUpdate(data: any) {
  // Handle update logic
  console.log('Resource updated:', data.id);
}

async function handleDelete(data: any) {
  // Handle deletion logic
  console.log('Resource deleted:', data.id);
}

export default genericWebhook;

Event Subscriptions

Webhooks can subscribe to platform events: delivery status updates for every outbound channel (WhatsApp, SMS, email, Messenger, Instagram, and the rest). When subscribed, your webhook’s execute function receives the event payload automatically.

Available Event Types

Event	Trigger
`message.sent`	The provider accepted the message
`message.delivered`	The message reached the recipient (channels that report delivery)
`message.read`	The recipient read the message (channels that report reads)
`message.failed`	The message could not be delivered; `error` carries the category and provider detail

Channels without receipts (Slack, Teams, Front, web chat) stop at message.sent.

Subscribing via CLI

lua webhooks list-events
lua webhooks subscribe --webhook-name my-webhook --event message.delivered
lua webhooks subscribe --webhook-name my-webhook --event message.read
lua webhooks unsubscribe --webhook-name my-webhook --event message.delivered

Event Payload Shape

When an event fires, your webhook receives a WebhookEvent where body is the delivery record, the same object Channels.getStatus returns:

interface DeliveryEventPayload {
  id: string;                 // deliveryId, also returned by Channels.*.send
  agentId: string;
  userId?: string;
  channel: string;            // 'whatsapp' | 'sms' | 'email' | 'messenger' | ...
  provider: string;           // 'meta' | 'vonage' | 'bird' | 'ses' | ...
  channelIdentifier: string;  // the sending phone number, inbox, or page
  recipient: string;
  providerMessageId?: string;
  messageWamid?: string;      // same as providerMessageId, kept for existing WhatsApp handlers
  conversationMessageId?: string;
  origin: 'agent_reply' | 'channels_send' | 'template' | 'system_template' | 'queued_flush' | 'admin_template' | 'notification' | 'unknown';
  templateName?: string;
  idempotencyKey?: string;
  status: 'queued' | 'accepted' | 'sent' | 'delivered' | 'read' | 'failed' | 'expired';
  error?: {
    category: 'window_closed' | 'unreachable' | 'billing' | 'opted_out' | 'throttled' | 'auth' | 'template' | 'media' | 'invalid_request' | 'compliance' | 'experiment' | 'provider' | 'unknown';
    provider: string;
    code: string;       // provider's own code, e.g. Meta 131042
    title: string;
    detail?: string;
  };
  events: Array<{ status: string; at: string; source: 'send' | 'callback' | 'sweep' }>;
  pricing?: { billable: boolean; category?: string; model?: string };
  createdAt: string;
  updatedAt: string;
  deliveredAt?: string;
  readAt?: string;
  failedAt?: string;
}

Delivery Semantics

Subscribed platform events are delivered at least once. Each event is durably queued and processed on isolated infrastructure with automatic retries — up to 3 attempts total, a fixed 60-second wait between attempts, retried only on failure. Your handler may therefore run more than once for a single logical event, so keep side effects idempotent. Each invocation receives event.execution:

Field	Description
`eventId`	Stable identifier for the logical event. Unchanged across retries and redeliveries — use it as your idempotency / dedup key.
`executionId`	Unique identifier for this individual attempt. Not a dedup key.
`attempt`	1-based attempt counter (`1` on the first delivery, `2` on the first retry, and so on).

execute: async (event) => {
  const { eventId } = event.execution ?? {};

  // Key side effects on eventId so a repeated delivery is a no-op
  await Data.create('delivery-events', {
    idempotencyKey: eventId,
    status: event.body.status,
  }, `${event.body.status} ${eventId}`);

  return { received: true };
}

event.execution is only present for durably-delivered platform events — it is undefined for synchronous direct requests to your webhook URL and during local lua test / lua dev runs. Very large event payloads (over 50,000 characters, which is rare) are delivered without the at-least-once retry guarantee.

Direct requests are unchanged. Requests sent straight to your webhook URL are still handled synchronously with no automatic retries — the caller receives your handler’s return value and applies its own retry policy. At-least-once delivery and event.execution apply only to subscribed platform events.

Example: Track Delivery for Analytics

import { LuaWebhook, Data } from 'lua-cli';

const analyticsWebhook = new LuaWebhook({
  name: 'message-analytics',
  description: 'Track message delivery for analytics',
  
  execute: async (event) => {
    const { body } = event;
    
    await Data.create('message-analytics', {
      messageId: body.messageWamid,
      recipient: body.recipientId,
      status: body.status,
      channel: body.channel,
      timestamp: body.timestamp,
      billable: body.pricing?.billable
    }, `${body.status} ${body.recipientId}`);
    
    return { tracked: true };
  }
});

export default analyticsWebhook;

Using with LuaAgent

Webhooks are added to your agent configuration:

import { LuaAgent } from 'lua-cli';
import stripeWebhook from './webhooks/stripe';
import shopifyWebhook from './webhooks/shopify';
import githubWebhook from './webhooks/github';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],
  
  webhooks: [
    stripeWebhook,
    shopifyWebhook,
    githubWebhook
  ]
});

Webhook URLs

After deploying, your webhooks can be called using either identifier:

https://webhook.heylua.ai/{agentId}/{webhookId}    // legacy + default
https://webhook.heylua.ai/{agentId}/{webhook-name} // friendly alias

Notes:

agentId is your agent identifier (e.g., agent_abc123)
webhookId is the UUID shown when you create the webhook
webhook-name is the name you pass to new LuaWebhook
You can copy both URLs after pushing: lua push webhook

Examples:

https://webhook.heylua.ai/agent_abc123/webhook_01JD3RZ9VX9W5
https://webhook.heylua.ai/agent_abc123/payment-webhook

Configure either URL in your external service (Stripe, Shopify, etc.)

Testing Webhooks

Local Testing

lua test
# Select: Webhook → your-webhook-name
# Provide test payload

Test Payloads

// Example test payload for Stripe
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_test_123",
      "amount": 2000,
      "currency": "usd",
      "metadata": {
        "orderId": "order_456"
      }
    }
  }
}

Security Best Practices

✅ Use Environment Variables

Never hardcode secrets

// ❌ Bad
secret: 'hardcoded_secret_key'

// ✅ Good
secret: env('STRIPE_WEBHOOK_SECRET')

✅ Validate Webhook Structure

Always validate incoming data

execute: async (event) => {
  const { body } = event;
  if (!body || !body.type) {
    throw new Error('Invalid webhook payload');
  }
  // Process webhook...
}

✅ Return Quickly

Webhook handlers should return fast (< 5 seconds)

// ✅ Queue long-running work
execute: async (event) => {
  const { body } = event;

  // Quick validation
  if (!isValid(body)) {
    return { error: 'Invalid' };
  }
  
  // Queue processing job
  await Jobs.create({
    execute: async () => {
      // Long-running work here
    }
  });
  
  return { received: true };
}

Error Handling

const robustWebhook = new LuaWebhook({
  name: 'robust-webhook',
  
  execute: async (event) => {
    try {
      const result = await processWebhook(event);
      
      return {
        success: true,
        result,
        timestamp: new Date().toISOString()
      };
      
    } catch (error) {
      // Log error for debugging
      console.error('Webhook error:', {
        error: error.message,
        stack: error.stack
      });
      
      // Return error status (don't throw!)
      return {
        success: false,
        error: error.message,
        timestamp: new Date().toISOString()
      };
    }
  }
});

Invoking an Agent from a Webhook

Use Agents.invoke to delegate work to a conversational agent after receiving a webhook event. Pass the user ID from the event payload so the invocation runs in that user’s context (conversation history is stored). If no user ID is available, omit userId and the invocation runs without user identity (no conversation history).

import { LuaWebhook, Agents } from 'lua-cli';

const orderShippedWebhook = new LuaWebhook({
  name: 'order-shipped-webhook',
  description: 'Delegate shipment notifications to the notification agent',

  execute: async (event) => {
    const { orderId, customerId, trackingNumber } = event.body ?? {};

    if (!customerId) {
      return { skipped: true, reason: 'no customerId in payload' };
    }

    const result = await Agents.invoke('notification-agent', {
      prompt: `Order ${orderId} has shipped. Tracking: ${trackingNumber}. Notify the customer.`,
      userId: customerId, // runs as this user — history is stored
    });

    return { notified: true, agentReply: result.text };
  },
});

export default orderShippedWebhook;

Agents API Reference

Full documentation for Agents.invoke — options, output shape, error handling, and more examples

Common Integrations

Stripe
Shopify
GitHub
Custom

Webhook Events:

payment_intent.succeeded
payment_intent.payment_failed
charge.refunded
invoice.payment_succeeded

Secret Location: Stripe Dashboard → Developers → Webhooks

Webhook Topics:

orders/create
orders/updated
products/create
products/delete

Secret Location: Shopify Admin → Settings → Notifications

Webhook Events:

push
pull_request
deployment_status
release

Secret Location: Repository → Settings → Webhooks

LuaAgent

Agent configuration

LuaTrigger

Declarative triggers that wake the agent instead of running code

Agents API

Invoke another agent from a webhook

Jobs API

Queue long-running work

User API

Send notifications

Data API

Store webhook data

​Overview

​Webhooks vs Triggers

​Use Cases

Payment Events

E-commerce Updates

Git Events

Custom Integrations

​User Access in Webhooks

​Constructor

​new LuaWebhook(config)

​Configuration Parameters

​Required Fields

​Optional Fields

​WebhookEvent Shape

​Complete Examples

​Stripe Payment Webhook

​Shopify Order Webhook

​GitHub Deployment Webhook

​Generic Webhook Template

​Event Subscriptions

​Available Event Types

​Subscribing via CLI

​Event Payload Shape

​Delivery Semantics

​Example: Track Delivery for Analytics

​Using with LuaAgent

​Webhook URLs

​Testing Webhooks

​Local Testing

​Test Payloads

​Security Best Practices

​Error Handling

​Invoking an Agent from a Webhook

Agents API Reference

​Common Integrations

​Related APIs

LuaAgent

LuaTrigger

Agents API

Jobs API

User API

Data API

​See Also

Overview

Webhooks vs Triggers

Use Cases

User Access in Webhooks

Constructor

new LuaWebhook(config)

Configuration Parameters

Required Fields

Optional Fields

WebhookEvent Shape

Complete Examples

Stripe Payment Webhook

Shopify Order Webhook

GitHub Deployment Webhook

Generic Webhook Template

Event Subscriptions

Available Event Types

Subscribing via CLI

Event Payload Shape

Delivery Semantics

Example: Track Delivery for Analytics

Using with LuaAgent

Webhook URLs

Testing Webhooks

Local Testing

Test Payloads

Security Best Practices

Error Handling

Invoking an Agent from a Webhook

Common Integrations

Related APIs

See Also