Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselamina.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Why This Matters

Most production Lamina integrations should use webhooks instead of tight polling loops. The local CLI can now do the same thing:
  • start a local webhook receiver
  • verify Lamina’s ED25519 signature
  • expose the listener through ngrok or another public tunnel
  • run a real app against that callback URL

​
Lamina Webhook Contract

When you start an execution with: 
POST /v1/apps/{appId}/runs?webhook=https://your-server.com/callback
Lamina sends a signed POST when the execution finishes. Headers:
  • X-Lamina-Webhook-Signature
  • X-Lamina-Webhook-Timestamp
  • X-Lamina-Webhook-Request-Id
Message to verify: 
<timestamp>.<raw_body>
Verification key source: 
GET /v1/webhooks/signing-key
The CLI listener and MCP listener both verify this contract directly.

​
Start A Local Listener

From the repository root: 
lamina webhook listen --port 8788
That starts a local receiver at: 
http://127.0.0.1:8788/lamina/webhook

​
Expose It Publicly

Use ngrok, cloudflared, or your preferred tunnel. Example with ngrok: 
ngrok http 8788
If the public URL is https://example.ngrok.dev, save it as the default Lamina webhook URL: 
lamina webhook listen \
  --port 8788 \
  --public-url https://example.ngrok.dev \
  --save-default
The CLI normalizes that to: 
https://example.ngrok.dev/lamina/webhook
Check what is saved: 
lamina webhook status
Clear it if needed: 
lamina webhook clear

​
Run An App Against The Saved Webhook URL

lamina run <appId> --file inputs.json --webhook default
You can also pass the public URL directly: 
lamina run <appId> \
  --file inputs.json \
  --webhook https://example.ngrok.dev/lamina/webhook

​
Expected Listener Output

For a successful callback, the listener prints a verified execution message like: 
Verified webhook 1 for execution 99ebc7c6-24f3-4fc2-9d53-2e3f49f3bec1 (completed)
If verification fails, the listener rejects the callback and prints the verification error instead.

​
Real End-To-End Flow

1

Authenticate the CLI

Run lamina login (browser OAuth) or lamina login --api-key lma_... for CI.
2

Start the local listener

Run lamina webhook listen --port 8788.
3

Expose the listener

Start ngrok or another tunnel and get a public HTTPS URL.
4

Save the public webhook URL

Start the listener with --public-url ... --save-default, or pass the full webhook URL directly when you run the app.
5

Run the app

Execute lamina run <appId> --file inputs.json --webhook default.
6

Receive and verify the callback

The local listener validates the Lamina signature and prints the completed execution.

​
MCP Uses Polling Instead

The hosted and local MCP servers intentionally expose only five high-level creative tools. They do not expose webhook listener management tools. For MCP clients, start work with lamina_create and retrieve results with lamina_status. Use REST webhooks when you are building a server-side integration that owns a public callback URL.

​
Fallback

If you do not want to expose a callback during local development, omit ?webhook= and use polling with: 
lamina run <appId> --file inputs.json --wait