Sonzai Docs

Webhooks & Notifications

Receive real-time event notifications via webhooks and poll for proactive agent messages.

Webhooks Overview

Register webhook URLs to receive HTTP POST callbacks when events occur. The platform sends a signed JSON payload to your endpoint whenever a subscribed event fires, enabling real-time integrations without polling.

Register a Webhook

Subscribe to an event type by providing a URL and optional authentication header.

const webhook = await client.webhooks.register("agent.message", {
  webhookUrl: "https://your-server.com/webhooks/sonzai",
  authHeader: "Bearer your-webhook-secret",
});

console.log(webhook.secret); // use to verify webhook signatures

Webhook Events

Available event types you can subscribe to:

agent.messageAgent sends a proactive message
agent.mood_changeAgent mood shifts significantly
agent.memory_addedNew memory extracted
agent.breakthroughSignificant personality milestone
agent.wakeupScheduled wakeup triggered
agent.consolidationMemory consolidation completed

Manage Webhooks

List, delete, inspect delivery attempts, and rotate secrets for your registered webhooks.

// List all webhooks
const webhooks = await client.webhooks.list();

// Delete a webhook
await client.webhooks.delete("agent.message");

// View delivery attempts
const attempts = await client.webhooks.listDeliveryAttempts("agent.message");

// Rotate webhook secret
const rotated = await client.webhooks.rotateSecret("agent.message");

Project-Scoped Webhooks

Register webhooks at the project level to receive events for all agents within a project.

await client.webhooks.registerForProject("project-id", "agent.message", {
  webhookUrl: "https://your-server.com/webhooks/project",
});

const projectWebhooks = await client.webhooks.listForProject("project-id");

Proactive Notifications (Polling)

Agents can generate proactive messages triggered by wakeups, mood shifts, or other internal events. Poll for pending notifications when push delivery is not feasible.

// List pending notifications
const notifications = await client.notifications.list("agent-id", {
  userId: "user-123",
  status: "pending",
});

for (const notif of notifications.items) {
  console.log(notif.type, notif.content);

  // Mark as consumed after processing
  await client.notifications.consume("agent-id", notif.id);
}

// View notification history
const history = await client.notifications.history("agent-id", {
  userId: "user-123",
  limit: 50,
});

Schedule Wakeups

Schedule proactive check-ins so agents reach out to users at specific times.

const wakeup = await client.agents.scheduleWakeup("agent-id", {
  userId: "user-123",
  scheduledAt: "2026-04-05T09:00:00Z",
  context: "Check in about the job interview preparation",
});

Webhooks vs. Notifications

Webhooks (push) deliver events to your server in real time via HTTP POST. Use webhooks when you have a server that can receive callbacks and you need instant notification of events.

Notifications (poll) queue proactive agent messages for you to fetch on demand. Use polling when your client cannot receive inbound HTTP requests (e.g., mobile apps, browser clients) or when you want to batch-process notifications on your own schedule.

← States, Tools & PrimingMemory-Aware Chat→