Events

The cPod event system is a real-time stream of platform activity. Every significant state change — an entity being created or updated, a pod transitioning status, a job completing, or a credential being revoked — emits an event. Events are immutable, append-only, and retained for 90 days.

Common event types include:

Type	Trigger
`person.created` / `person.updated` / `person.deleted`	People domain mutations
`pod.created` / `pod.started` / `pod.stopped` / `pod.failed`	Pod lifecycle transitions
`job.completed` / `job.failed`	Workflow job completions
`credential.created` / `credential.revoked`	Credential management
`custom.*`	Custom events emitted by your application

Event Schema

Field	Type	Description
`id`	`string`	UUID — unique per event
`type`	`string`	Dot-namespaced event type (e.g. `pod.failed`)
`resourceId`	`string`	ID of the affected resource
`resourceType`	`string`	Resource kind (e.g. `pod`, `person`, `job`)
`organizationId`	`string`	Organization scope
`workspaceId`	`string`	Workspace scope (if applicable)
`payload`	`object`	Event-specific data (varies by type)
`timestamp`	`string`	ISO 8601 UTC — when the event occurred

List Recent Events

import { CpodClient } from '@cpod/sdk'
const sdk = CpodClient.fromEnv()
 
const result = await sdk.events.getHistory({
  organizationId: 'b2c3d4e5-...',
  resourceType: 'pod',
  since: '2026-05-01T00:00:00Z',
  limit: 50,
})
 
for (const event of result.data) {
  console.log(event.timestamp, event.type, event.resourceId)
}

from cpod import CpodClient
sdk = CpodClient.from_env()
 
result = await sdk.events.get_history(
    organization_id="b2c3d4e5-...",
    resource_type="pod",
    since="2026-05-01T00:00:00Z",
    limit=50,
)
 
for event in result.data:
    print(event.timestamp, event.type, event.resource_id)

import "github.com/cpod-ai/cpod-sdk-go/events"
 
client := cpod.New(os.Getenv("CPOD_API_KEY"))
 
result, err := client.Events.GetHistory(ctx, events.HistoryOptions{
    OrganizationID: "b2c3d4e5-...",
    ResourceType:   "pod",
    Since:          "2026-05-01T00:00:00Z",
    Limit:          50,
})
for _, e := range result.Data {
    fmt.Println(e.Timestamp, e.Type, e.ResourceID)
}

Filter by Event Types

// Fetch only pod failure and job failure events
const result = await sdk.events.getHistory({
  organizationId: 'b2c3d4e5-...',
  types: ['pod.failed', 'job.failed'],
  since: new Date(Date.now() - 86400_000).toISOString(), // last 24 hours
})

from datetime import datetime, timedelta, timezone
 
result = await sdk.events.get_history(
    organization_id="b2c3d4e5-...",
    types=["pod.failed", "job.failed"],
    since=(datetime.now(timezone.utc) - timedelta(days=1)).isoformat(),
)

since := time.Now().Add(-24 * time.Hour).UTC().Format(time.RFC3339)
 
result, err := client.Events.GetHistory(ctx, events.HistoryOptions{
    OrganizationID: "b2c3d4e5-...",
    Types:          []string{"pod.failed", "job.failed"},
    Since:          since,
})

The SDK provides a lightweight poll-based subscription API for reacting to events in long-running processes.

const sub = sdk.events.subscribe(
  {
    organizationId: 'b2c3d4e5-...',
    types: ['pod.failed', 'pod.stopped'],
  },
  (event) => {
    console.log('Pod event:', event.type, event.resourceId, event.payload)
  }
)
 
// Dispatch incoming events (e.g. from a webhook payload or SSE frame)
sdk.events.dispatch(incomingEvent)
 
// Stop receiving events
sub.unsubscribe()

def handle_event(event):
    print("Pod event:", event.type, event.resource_id, event.payload)
 
sub = sdk.events.subscribe(
    filter={"organization_id": "b2c3d4e5-...", "types": ["pod.failed", "pod.stopped"]},
    handler=handle_event,
)
 
# Dispatch an incoming event (e.g. from a webhook or SSE frame)
sdk.events.dispatch(incoming_event)
 
# Stop receiving events
sub.unsubscribe()

sub := client.Events.Subscribe(
    events.EventFilter{
        OrganizationID: "b2c3d4e5-...",
        Types:          []string{"pod.failed", "pod.stopped"},
    },
    func(e events.CpodEvent) {
        fmt.Println("Pod event:", e.Type, e.ResourceID)
    },
)
 
// Dispatch an incoming event
client.Events.Dispatch(incomingEvent)
 
// Stop receiving events
sub.Unsubscribe()

Real-Time Subscriptions via Webhooks

For real-time delivery of events to external services (HTTP endpoints, queues, etc.), use webhooks. Webhooks push events to your endpoint as they occur, without polling. Configure webhooks in the cPod dashboard under Settings → Webhooks.

Webhook payloads use the same CpodEvent schema as the REST API. Verify the X-Cpod-Signature header on incoming requests to confirm authenticity.

Emit a Custom Event

Your application can emit custom events into the platform stream. Use a custom.* type prefix.

// Custom events are dispatched via the emulator's POST /v1/events endpoint
// or through your platform's event ingestion API.
await fetch(`${process.env.CPOD_BASE_URL}/v1/events`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CPOD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'custom.report.generated',
    resourceId: 'report-xyz',
    resourceType: 'report',
    payload: { format: 'pdf', rows: 1240 },
  }),
})

import httpx, os
 
async with httpx.AsyncClient() as client:
    await client.post(
        f"{os.environ['CPOD_BASE_URL']}/v1/events",
        headers={"Authorization": f"Bearer {os.environ['CPOD_API_KEY']}"},
        json={
            "type": "custom.report.generated",
            "resourceId": "report-xyz",
            "resourceType": "report",
            "payload": {"format": "pdf", "rows": 1240},
        },
    )

body := map[string]any{
    "type":         "custom.report.generated",
    "resourceId":   "report-xyz",
    "resourceType": "report",
    "payload":      map[string]any{"format": "pdf", "rows": 1240},
}
data, _ := json.Marshal(body)
 
req, _ := http.NewRequest("POST", os.Getenv("CPOD_BASE_URL")+"/v1/events", bytes.NewReader(data))
req.Header.Set("Authorization", "Bearer "+os.Getenv("CPOD_API_KEY"))
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

Pods Overview