Skip to main content

​
Why Executions Are Asynchronous

Some Lamina apps complete in seconds. Others, especially multi-step image/video pipelines, may take much longer. Because of that, POST /api/apps/{appId}/executions starts work and returns an execution handle immediately instead of blocking until the final output is ready.

​
Two Ways To Get Results

Pass a webhook URL as a query parameter. When the execution completes, we POST the results to your URL. 
POST /api/apps/{appId}/executions?webhook=https://your-server.com/callback
Benefits:
  • No polling loop needed
  • Results arrive as soon as they’re ready
  • Signed with ED25519 for security
  • Automatic retries (3 attempts with backoff)

​
Option 2: Polling

Poll GET /api/executions/{executionId} on an interval until status is completed or failed. Use different polling intervals depending on the workflow:
  • Short image jobs: every 3-5 seconds
  • Heavier multi-step jobs: every 5-10 seconds
  • Long-running video jobs: every 10-15 seconds
Avoid polling every second in production.
1

Start the execution

Call POST /api/apps/{appId}/executions?webhook=<your_url> and store the returned executionId.
2

Persist the execution ID

Save it in your job table, queue, or request state so you can resume later.
3

Receive results

Your webhook endpoint receives the completed results, or poll GET /api/executions/{executionId} as a fallback.

​
What To Store

For every execution you start, store at least:
  • executionId
  • appId
  • input payload
  • current status
  • started timestamp
This makes retries, dashboards, and support much easier.

​
Failure Handling

If an execution fails:
  • inspect the top-level errorMessage
  • inspect each output’s error
  • keep the original inputs for debugging or replay
If your product has end users, show a user-friendly status while keeping the raw error for logs and support tooling.

​
Webhook Verification

When receiving webhook callbacks, verify the signature to ensure it’s from Lamina:
  1. Fetch the public key from GET /api/webhooks/signing-key
  2. Verify the ED25519 signature: verify(signature, "<timestamp>.<body>", publicKey)
  3. Reject timestamps older than 5 minutes (replay protection)
See the Webhook Signing Key reference for verification code examples.