Lifecycle Webhooks

Overview

Synapse can POST JSON payloads to your endpoint whenever lifecycle events occur — sandbox creation, execution completion, pause/resume, or kills.

Tip

Webhooks enable event-driven architectures where your backend reacts to sandbox events without polling.

Supported Events

Event	Description
cell.created	A new sandbox was created
cell.killed	A sandbox was destroyed
cell.paused	A sandbox was paused (snapshot created)
cell.resumed	A sandbox was resumed from snapshot
exec.completed	Code execution finished
*	Subscribe to all events

Register a Webhook

Python

from synapse import Cell

webhook = Cell.register_webhook(
    url="https://your-server.com/hooks/synapse",
    events=["cell.created", "exec.completed"],
)
print(webhook["webhook_id"])  # "wh_a1b2c3..."

TypeScript

import { Cell } from '@runsynapse/sdk';

const webhook = await Cell.registerWebhook(
  "https://your-server.com/hooks/synapse",
  ["cell.created", "exec.completed"],
);
console.log(webhook.webhook_id);

cURL

curl -X POST http://localhost:8001/v1/webhooks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/hooks/synapse", "events": ["*"]}'

Webhook Payload

When an event fires, the gateway sends a POST request:

{
  "event": "exec.completed",
  "cell_id": "abc123-def456-...",
  "detail": {
    "execution_id": "exec_a1b2c3",
    "exit_code": 0,
    "latency_ms": 0.24
  },
  "timestamp": 1715702400000
}

List Webhooks

Python

webhooks = Cell.list_webhooks()
for wh in webhooks:
    print(f"{wh['webhook_id']}: {wh['url']} -> {wh['events']}")

TypeScript

const webhooks = await Cell.listWebhooks();
webhooks.forEach(wh => console.log(`${wh.webhook_id}: ${wh.url}`));

Delete a Webhook

Cell.delete_webhook("wh_a1b2c3...")

Query Lifecycle Events

You can also poll events directly without webhooks:

# Per-cell events
events = cell.get_lifecycle_events()

# Global events (last 100)
events = Cell.get_global_events()

Use Cases

• Billing integration — Track exec.completed to count executions
• Monitoring — Alert on cell.killed to detect unexpected terminations
• CI/CD pipelines — Trigger downstream jobs when exec.completed
• Audit logging — Archive all lifecycle events for compliance