Skip to main content
When you submit a run, you can supply a list of URLs that Lyceum Cloud will call with completion info once the execution finishes. This is the right tool when you don’t want to poll the API yourself. Common patterns:
  • A backend that submits a long training job and wants to be notified when it’s done
  • A queue worker that fans out runs and needs to mark them complete in its own database
  • A CI pipeline waiting on a remote build
For interactive workflows where a human is watching, the dashboard or lyceum workloads list is simpler.

​
How it works

The execution request body for all three execution types accepts a user_callback_urls field — a list of HTTPS URLs. When the run reaches a terminal state (completed, failed, system_failure, aborted, cancelled), Lyceum POSTs job completion info to each URL. The same field exists on:
  • Python runs (POST /execution/streaming/start)
  • Docker image runs (POST /execution/image/start)
  • Docker Compose runs (POST /execution/compose/start)

​
Submitting a callback

curl -X POST https://api.lyceum.technology/api/v2/external/execution/streaming/start \
  -H "Authorization: Bearer $LYCEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(1+1)",
    "machine_type": "cpu",
    "user_callback_urls": [
      "https://your-service.example.com/lyceum-webhook"
    ]
  }'
You can supply more than one URL — useful for fanning out to multiple downstream systems.

​
Receiving the callback

The endpoint at the URL you registered will receive an HTTPS POST when the run finishes. Build your handler to:
  • Return 2xx quickly — Lyceum doesn’t need a body, just an acknowledgement
  • Verify the source — gate the endpoint behind a shared secret in the URL path or a header you control, since Lyceum doesn’t sign callbacks
  • Be idempotent — handle the case where a callback is delivered more than once

​
Combining with secrets

If your callback handler requires a token (e.g. an HMAC secret you check), put it in an environment variable on Lyceum Secrets and reference it in the URL or as a query parameter when you submit the run. That keeps the secret out of your codebase.