Webhooks

What are Webhooks?

Webhooks are HTTP endpoints that allow external services to send events to your agent. When something happens in an external system (like a payment completing or an order shipping), that system can notify your agent in real-time.

Think of it as:

A phone number for your agent - external services can “call” it when events happen

No Conversational Context: Webhooks execute outside of user conversations. You MUST provide a userId when calling User.get(userId) to notify specific users. Store user IDs in your payment/order metadata.

Built-in webhook support for seamless external integrations.

Why Webhooks?

Real-Time Events

Get notified instantly when events happen in external systems

Automated Actions

Automatically respond to external events without user interaction

Seamless Integration

Connect with Stripe, Shopify, GitHub, and any webhook-enabled service

Event-Driven

Build reactive agents that respond to real-world events

How Webhooks Work

External Event Occurs

Something happens: payment completes, order ships, PR merges, etc.

Service Sends HTTP Request

The external service (Stripe, Shopify) sends a POST request to your webhook URL

Your Webhook Receives Event

Your LuaWebhook’s execute function is called with the event data

Your Code Takes Action

Process the event: update orders, notify users, trigger jobs, etc.

Return Response

Return acknowledgment to the external service

Simple Example

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

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle Stripe payment events',
  
  execute: async (event) => {
    const { body } = event;
    if (body?.type === 'payment_intent.succeeded') {
      // ⚠️ Webhooks have NO conversational context
      // You MUST provide userId to User.get()
      
      // Get user ID from payment metadata
      const customerId = body.data?.object?.metadata?.customerId;
      
      if (!customerId) {
        console.error('No customerId in payment metadata');
        return { received: true, error: 'No customer ID' };
      }
      
      // Retrieve specific user by ID
      const user = await User.get(customerId);
      
      // Send payment confirmation to that user
      await user.send([{
        type: 'text',
        text: `✅ Payment confirmed! Amount: ${body.data.object.amount} ${body.data.object.currency.toUpperCase()}`
      }]);
    }
    
    return { received: true };
  }
});

Critical: Webhooks execute outside conversational context. User.get() REQUIRES a userId parameter. Always store the user ID in your payment/order metadata when creating transactions.

Common Use Cases

Payments
E-commerce
Development
Custom

Stripe, PayPal, SquareHandle payment events:

Payment succeeded
Payment failed
Refund processed
Subscription updated

Actions:

Update order status
Notify customer
Trigger fulfillment

Event Subscriptions

Webhooks can also subscribe to platform events — real-time notifications from your messaging channels. When you send a template message via WhatsApp, for example, you can track whether it was delivered, read, or failed.

Webhook event subscriptions for message delivery tracking. Currently supports WhatsApp status events; additional channels may be added in the future.

Available Event Types

Event	Description	Channel
`message.sent`	Message was sent to the recipient	WhatsApp
`message.delivered`	Message was delivered to the recipient’s device	WhatsApp
`message.read`	Recipient read the message	WhatsApp
`message.failed`	Message failed to send	WhatsApp
`message.played`	Recipient played a voice/video message	WhatsApp

How It Works

Create a webhook

Define a LuaWebhook that handles delivery status events

Subscribe to events

Use the CLI to subscribe your webhook to the event types you care about

lua webhooks subscribe --webhook-name delivery-tracker --event message.delivered
lua webhooks subscribe --webhook-name delivery-tracker --event message.read
lua webhooks subscribe --webhook-name delivery-tracker --event message.failed

Receive events

Your webhook’s execute function is called with the event payload whenever a status update arrives

Delivery Semantics

Subscribed platform events are delivered at least once. Each event is durably queued and processed on isolated infrastructure, so a subscribed handler may run more than once for a single logical event:

Delivery is retried automatically — up to 3 attempts total, with a fixed 60-second wait between attempts, and only when an attempt fails.
Because retries (and occasional redeliveries) can repeat an event, your handler’s side effects should be idempotent — safe to run twice.

Each invocation receives execution metadata on 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 during local lua test / lua dev runs, which execute in-process. 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 (Stripe, Shopify, GitHub, etc.) 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: Delivery Tracking Webhook

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

const deliveryTracker = new LuaWebhook({
  name: 'delivery-tracker',
  description: 'Track WhatsApp message delivery status',
  
  execute: async (event) => {
    const { body } = event;
    const { eventType, recipientId, status, messageWamid } = body;
    
    await Data.create('delivery-events', {
      messageId: messageWamid,
      recipient: recipientId,
      status: status,
      eventType: eventType,
      trackedAt: new Date().toISOString()
    }, `${status} - ${recipientId}`);
    
    if (status === 'failed') {
      console.error(`Message ${messageWamid} failed for ${recipientId}`);
    }
    
    return { received: true };
  }
});

export default deliveryTracker;

Managing Subscriptions via CLI

# List all available event types
lua webhooks list-events

# Subscribe a webhook to an event
lua webhooks subscribe --webhook-name delivery-tracker --event message.delivered

# Unsubscribe a webhook from an event
lua webhooks unsubscribe --webhook-name delivery-tracker --event message.delivered

Adding Webhooks to Your Agent

Webhooks are added to your LuaAgent configuration:

import { LuaAgent } from 'lua-cli';
import paymentWebhook from './webhooks/payment';
import orderWebhook from './webhooks/order';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  
  // Add webhooks
  webhooks: [
    paymentWebhook,
    orderWebhook
  ]
});

Webhook URLs

After deploying, you can call webhooks by ID or by name:

https://webhook.heylua.ai/{agentId}/{webhookId}
https://webhook.heylua.ai/{agentId}/{webhook-name}

Notes:

agentId is your agent identifier (e.g., agent_abc123)
webhookId is the UUID shown when the webhook is created
webhook-name is the friendly name from your code
lua push webhook prints both links

Configure either URL in your external service’s webhook settings.

Verify Requests

A webhook URL is public: anyone who knows or guesses it can invoke your execute function. Add a secret to the webhook definition and Lua will only run it for requests that prove they know that secret.

import { LuaWebhook } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  description: 'Handle payment events',
  secret: 'a-long-random-string',

  execute: async (event) => {
    // Only reached when the signature checks out
    return { received: true };
  },
});

With a secret set, every request must carry:

x-lua-signature: sha256=<hex HMAC-SHA256 of the raw request body, keyed with the secret>

Requests with a missing, malformed, or incorrect signature get 401 and your code never runs. Webhooks with no secret behave exactly as before — this is opt-in.

The signature is computed over the exact bytes of the request body, not over a re-serialized copy. A sender that pretty-prints or reorders JSON after signing will fail verification.

Signing covers JSON request bodies. A sender that posts application/x-www-form-urlencoded or text/plain will always be rejected, so leave secret unset for those and verify inside your execute function instead.

Computing the signature

The sender computes the HMAC. In a shell:

SECRET='a-long-random-string'
BODY='{"type":"payment_intent.succeeded","amount":2000}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://webhook.heylua.ai/{agentId}/payment-webhook" \
  -H "Content-Type: application/json" \
  -H "x-lua-signature: sha256=$SIG" \
  -d "$BODY"

In Node.js:

import { createHmac } from 'crypto';

const body = JSON.stringify({ type: 'payment_intent.succeeded', amount: 2000 });
const signature = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');

await fetch(`https://webhook.heylua.ai/${agentId}/payment-webhook`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-lua-signature': signature },
  body, // the same string that was signed
});

Rotating the secret

Change the value in your webhook definition and re-deploy — lua push webhook applies the current secret to the webhook on every push:

lua push webhook
lua webhooks deploy --webhook-name payment-webhook --webhook-version latest

Update the sender at the same time; requests signed with the old secret start failing as soon as the push lands. To turn verification off again, set secret: '' and push.

The secret must be a literal string or a constant the CLI can read at build time — a value like process.env.WEBHOOK_SECRET cannot be resolved during compilation and fails the build rather than silently deploying an unprotected webhook. Treat the file holding it as a credential.

Don’t put a signing secret on a webhook you publish as a marketplace template. The secret is part of the compiled webhook code, and publishing a template freezes that code for every installer — they would all receive your key. Publish the webhook without a secret and let each installer set their own.

Vendors that sign with their own scheme (Stripe’s stripe-signature, GitHub’s x-hub-signature-256) won’t produce an x-lua-signature header. Leave secret unset for those and verify the vendor’s header inside your execute function.

Best Practices

✅ Store User IDs in Metadata

Always include user ID in payment/order metadataWhen creating payments or orders, store the Lua user ID:

// When creating Stripe payment
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  metadata: {
    customerId: user.id,  // ← Lua user ID
    orderId: order.id
  }
});

Then in your webhook, retrieve the specific user:

execute: async (event) => {
  const { body } = event;
  const customerId = body.data.object.metadata.customerId;
  const user = await User.get(customerId);
  await user.send([{ type: 'text', text: 'Payment confirmed!' }]);
}

✅ Handle Errors Gracefully

Don’t throw errors - return error status

execute: async (event) => {
  const { body } = event;
  try {
    // Process webhook
    return { success: true };
  } catch (error) {
    console.error('Webhook error:', error);
    return { success: false, error: error.message };
  }
}

✅ Return Quickly

Webhooks should respond within 5 secondsFor long-running work, queue a job:

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

Next Steps

Webhooks API Reference

Complete API documentation with examples

Agent Concept

Learn about LuaAgent configuration

Jobs Concept

Understand scheduled tasks

Skills Concept

Learn about skills and tools

Welcome

Build with AI

Key Concepts

Featured Demos

What are Webhooks?

Think of it as:

Why Webhooks?

Real-Time Events

Automated Actions

Seamless Integration

Event-Driven

How Webhooks Work

Simple Example

Common Use Cases

Event Subscriptions

Available Event Types

How It Works

Delivery Semantics

Example: Delivery Tracking Webhook

Managing Subscriptions via CLI

Adding Webhooks to Your Agent

Webhook URLs

Verify Requests

Computing the signature

Rotating the secret

Best Practices

Next Steps

Webhooks API Reference

Agent Concept

Jobs Concept

Skills Concept

​What are Webhooks?

Think of it as:

​Why Webhooks?

Real-Time Events

Automated Actions

Seamless Integration

Event-Driven

​How Webhooks Work

​Simple Example

​Common Use Cases

​Event Subscriptions

​Available Event Types

​How It Works

​Delivery Semantics

​Example: Delivery Tracking Webhook

​Managing Subscriptions via CLI

​Adding Webhooks to Your Agent

​Webhook URLs

​Verify Requests

​Computing the signature

​Rotating the secret

​Best Practices

​Next Steps

Webhooks API Reference

Agent Concept

Jobs Concept

Skills Concept

What are Webhooks?

Why Webhooks?

How Webhooks Work

Simple Example

Common Use Cases

Event Subscriptions

Available Event Types

How It Works

Delivery Semantics

Example: Delivery Tracking Webhook

Managing Subscriptions via CLI

Adding Webhooks to Your Agent

Webhook URLs

Verify Requests

Computing the signature

Rotating the secret

Best Practices

Next Steps