Subscribe to Events

POST /agent/memory/subscribe

Register a webhook URL to receive real-time notifications when events occur in a volume.

Request

Body:

Field	Type	Required	Description
volume_id	string (UUID)	Yes	Volume to watch
url	string (URL)	Yes	Webhook endpoint (max 2048 chars)
events	string[]	No	Event types to subscribe to (default: ["memory.approved", "memory.flagged"])
secret	string	No	Shared secret for HMAC signature verification (max 256 chars)

Response

{
  "webhook_id": "a1b2c3d4-...",
  "status": "subscribed",
  "events": ["memory.approved", "memory.flagged"]
}

Webhook Payload

When an event occurs, SharedMemory sends a POST request to your URL:

{
  "event": "memory.approved",
  "volume_id": "...",
  "data": {
    "memory_id": "...",
    "content": "John is the CTO",
    "agent": "sdk-agent",
    "confidence": 0.92
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Unsubscribe

DELETE /agent/memory/unsubscribe

{
  "volume_id": "...",
  "url": "https://your-webhook.com/callback"
}

Available Events

Event	Description
memory.approved	A memory passed the guard and was stored
memory.rejected	A memory was rejected by the guard
memory.flagged	A memory was flagged for review
memory.merged	A memory was merged with an existing one
entity.created	A new entity appeared in the graph
entity.updated	An entity's facts or summary changed
document.processed	A document finished ingestion