Webhooks

MIOSA sends HTTP POST requests to your endpoint whenever a sandbox or deployment changes state. Use webhooks to update your database, notify users, trigger downstream actions, or bill for compute.

Event taxonomy

Sandbox events

Deployment events

Forge events

Every Forge event names its repository in the payload (repository.id, repository.full_name, repository.owner, repository.slug), so one organization subscription can route events from every repository. Subscriptions cannot be limited to a single repository.

Payload structure

Every webhook delivery has the same envelope:

{
  "id": "evt_01hzqmrkntq6g9gxnqhvpa8c7t",
  "type": "sandbox.running",
  "created_at": "2026-05-25T14:32:10Z",
  "data": {
    "id": "sbx_01hzq5pnmpgt6vdwp0r8d23c5n",
    "state": "running",
    "external_user_id": "user_42",
    "external_project_id": "proj_lumen_1",
    "metadata": {
      "customer_id": "user_42",
      "project_name": "brand-refresh",
      "source": "lumen-whitelabel"
    },
    "preview_url": "https://3000-sbx01hzq.sandbox.example.com"
  }
}

The id field is a unique event ID. Use it to deduplicate deliveries.

HMAC-SHA256 signature verification

Every delivery includes a Miosa-Signature header:

Miosa-Signature: t=1716645130,v1=a3f2c8...

• t - Unix timestamp (seconds) when MIOSA signed the request
• v1 - HMAC-SHA256 hex digest of "<t>.<raw_body>"

The signed payload is timestamp + "." + raw request body bytes. Verify before parsing the JSON.

Idempotency

MIOSA may deliver the same event more than once (network retries, at-least-once semantics). Make your handler idempotent by storing the event id and discarding duplicates:

processed_events = set()  # use a database or cache in production

def handle_event(event: dict) -> None:
    event_id = event["id"]
    if event_id in processed_events:
        return  # duplicate  -  skip
    processed_events.add(event_id)

    match event["type"]:
        case "sandbox.running":
            notify_user(event["data"]["external_user_id"])
        case "sandbox.destroyed":
            release_resources(event["data"]["id"])
        case "sandbox.error":
            alert_oncall(event["data"])

Retry policy

MIOSA makes up to eight delivery attempts over roughly 15.5 hours (within a 24-hour window), then drops the event. If your endpoint is unreachable, check the webhook delivery log in the MIOSA dashboard.

Return a 2xx status code within 10 seconds to acknowledge receipt. If your processing takes longer, acknowledge immediately and handle the event asynchronously.

Register a webhook

Local testing

Use a tunnel to expose your local server during development:

# Option 1  -  ngrok
ngrok http 8000
# Copy the https URL, set MIOSA_WEBHOOK_URL in .env

# Option 2  -  cloudflared
cloudflared tunnel --url http://localhost:8000

Then run the one-time setup script to register the tunnel URL as your webhook endpoint. When you restart the tunnel and get a new URL, update the webhook:

# Update an existing webhook's URL
client.webhooks.update("whk_abc123", url="https://new-tunnel.ngrok.io/webhooks/miosa")

See also

• End-to-end white-label walkthrough
• Preview Tokens
• Sandbox API reference