Webhook＆通知
Webhookを介したリアルタイムのイベント通知の受信と、プロアクティブなエージェントメッセージのポーリング。
Webhookの概要
イベント発生時にHTTP POSTコールバックを受信するためにWebhook URLを登録します。プラットフォームは、サブスクライブされたイベントが発生するたびに署名付きJSONペイロードをエンドポイントに送信し、ポーリングなしのリアルタイム統合を可能にします。
Webhookの登録
URLとオプションの認証ヘッダーを提供して、イベントタイプにサブスクライブします。
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 signaturesWebhookイベント
サブスクライブ可能なイベントタイプ：
agent.messageエージェントがプロアクティブなメッセージを送信agent.mood_changeエージェントのムードが大きく変化agent.memory_added新しい記憶が抽出されたagent.breakthrough重要なパーソナリティのマイルストーンagent.wakeupスケジュールされたウェイクアップがトリガーagent.consolidation記憶の統合が完了Webhookの管理
登録済みWebhookの一覧表示、削除、配信試行の確認、シークレットのローテーションを行います。
// 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");プロジェクトスコープのWebhook
プロジェクトレベルでWebhookを登録し、プロジェクト内のすべてのエージェントのイベントを受信します。
await client.webhooks.registerForProject("project-id", "agent.message", {
webhookUrl: "https://your-server.com/webhooks/project",
});
const projectWebhooks = await client.webhooks.listForProject("project-id");プロアクティブ通知（ポーリング）
エージェントは、ウェイクアップ、ムードの変化、その他の内部イベントによってトリガーされたプロアクティブなメッセージを生成できます。プッシュ配信が不可能な場合は、保留中の通知をポーリングします。
// 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,
});ウェイクアップのスケジュール
エージェントが特定の時間にユーザーに連絡を取るよう、プロアクティブなチェックインをスケジュールします。
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",
});Webhookと通知の違い
Webhook（プッシュ）はHTTP POSTを介してリアルタイムでサーバーにイベントを配信します。コールバックを受信できるサーバーがあり、イベントの即時通知が必要な場合に使用します。
通知（ポーリング）はプロアクティブなエージェントメッセージをキューに入れ、オンデマンドで取得できるようにします。クライアントがインバウンドHTTPリクエストを受信できない場合（モバイルアプリ、ブラウザクライアントなど）や、独自のスケジュールで通知をバッチ処理したい場合に使用します。