Card-Change Notifications

Two complementary surfaces for reacting to canonical card changes without polling:

Server-Sent Events at GET /v1/agents/{id}/stream — long-lived HTTP connection; you receive a card_changed SSE frame whenever the agent’s canonical card recomposes.
Signed webhook subscriptions at POST /v1/agents/{id}/notifications/webhook — Mnemom POSTs a signed payload to your URL on each canonical change.

Both surfaces read from the transparency log. This is a distinct mechanism from the org-level Webhook Notifications system — different endpoints, its own signing convention (below), and scoped to one agent’s card rather than a whole org’s event stream.

Both surfaces are gated per-agent by agents.sse_enabled / agents.webhook_enabled, which default to off. There is currently no self-service API to flip these flags — contact support to enable card-change notifications for an agent. Until enabled, both endpoints return 404 (to avoid enumerating which agents exist).

SSE channel

Connect

curl -N -H "Authorization: Bearer $TOKEN" \
  https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/stream

The response is Content-Type: text/event-stream. Each canonical change emits a frame like:

event: card_changed
id: 4711
data: {"agent_id":"smolt-e2ca60ef","card_kind":"alignment","content_hash":"...","version":17,"composed_at":"2026-05-22T12:00:00Z","log_index":4711,"attestation_jws":"..."}

Reconnect with a cursor

The id field on each frame is the transparency-log log_index. On reconnect, pass it as Last-Event-ID (standard SSE reconnection header) or as the since query parameter — Last-Event-ID takes precedence when both are present:

curl -N -H "Authorization: Bearer $TOKEN" \
  -H "Last-Event-ID: 4711" https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/stream
# OR
curl -N -H "Authorization: Bearer $TOKEN" \
  "https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/stream?since=4711"

Frames are delivered strictly in log_index ascending order, so the cursor is monotone.

Stream lifetime

Each connection caps at 5 minutes. Reconnect with the latest cursor — EventSource implementations handle this automatically. A : keepalive <timestamp> comment frame is emitted every 15 seconds; a final event: close frame fires before the connection drops.

Webhook channel

curl -X POST https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/notifications/webhook \
  -H "Authorization: Bearer $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.example.com/mnemom/card-changed",
    "consumer_id": "tenant-a"
  }'

Response:

{
  "subscription_id": "sub-3e8f...",
  "webhook_url": "https://your-server.example.com/mnemom/card-changed",
  "secret": "wEbHt73...JNkP",
  "expires_at": "2026-06-21T00:00:00Z"
}

The secret is shown exactly once — store it server-side. Mnemom holds only its hash. Subscriptions expire after 30 days by default unless you pass an explicit expires_at.

Delivery shape

On every canonical card change, Mnemom POSTs to your URL:

{
  "type": "card_changed",
  "delivered_at": "2026-05-22T12:00:01.234Z",
  "data": {
    "agent_id": "smolt-e2ca60ef",
    "card_kind": "alignment",
    "content_hash": "...",
    "version": 17,
    "composed_at": "2026-05-22T12:00:00Z",
    "log_index": 4711,
    "attestation_jws": "..."
  }
}

With headers:

X-Mnemom-Webhook-Id: sub-3e8f...
X-Mnemom-Signature: t=1716393600,v1=<hex-hmac-sha256>
User-Agent: mnemom-cards/1 (+https://mnemom.ai/v1)
Content-Type: application/json

This is a different header pair from the org-level Webhook Notifications system (X-Webhook-Id / X-Webhook-Signature, no Mnemom- prefix) — don’t share verification code between the two without checking the header names.

Verify the signature

The HMAC-SHA256 signature is computed over the string <timestamp>.<raw-body>:

import hmac, hashlib

def verify_mnemom_webhook(body: str, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t = parts["t"]
    expected = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

List active subscriptions

curl https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/notifications \
  -H "Authorization: Bearer $MNEMOM_API_KEY"

Returns each subscription’s subscription_id, channel (webhook or sse), consumer_id, webhook_url, and last_sent_log_index — never the secret.

Idempotent delivery

Each subscription tracks last_sent_log_index. If the same log entry is re-processed (e.g. a reconciler closes a gap that the normal compose path also closed), delivery is skipped for any subscription whose last_sent_log_index is already at or past that entry.

Unsubscribe

curl -X DELETE https://api.mnemom.ai/v1/agents/smolt-e2ca60ef/notifications/sub-3e8f... \
  -H "Authorization: Bearer $MNEMOM_API_KEY"

Returns 204 on success, 404 if the subscription is already gone (idempotent).

Webhook URL constraints

https:// only — http:// URLs are rejected.
No loopback, RFC 1918, link-local, multicast, or reserved address space (IPv4 or IPv6).
No .local / .internal hostnames.

These defend against SSRF on outbound delivery. For local development, tunnel with ngrok or cloudflared.

SSE vs webhook — which to use

Use case	Channel
Backend service that can keep an HTTP connection open	SSE
Serverless / Lambda / Cloud Functions that prefer push-on-event	Webhook
Browser / dashboard UI consuming card changes	SSE (via `EventSource`)
Compliance / SIEM / archive that wants a durable POST trail	Webhook

Both surfaces deliver from the same event source (the transparency log) — subscribing to both is fine.

Identity & Cards

Posture & Policy

Detection & Safe House

AEGIS

Reputation & Risk

Lifecycle

Card-Change Notifications

SSE channel

Connect

Reconnect with a cursor

Stream lifetime

Webhook channel

Delivery shape

Verify the signature

List active subscriptions

Idempotent delivery

Unsubscribe

Webhook URL constraints

SSE vs webhook — which to use

See also

​SSE channel

​Connect

​Reconnect with a cursor

​Stream lifetime

​Webhook channel

​Subscribe

​Delivery shape

​Verify the signature

​List active subscriptions

​Idempotent delivery

​Unsubscribe

​Webhook URL constraints

​SSE vs webhook — which to use

​See also

SSE channel

Connect

Reconnect with a cursor

Stream lifetime

Webhook channel

Subscribe

Delivery shape

Verify the signature

List active subscriptions

Idempotent delivery

Unsubscribe

Webhook URL constraints

SSE vs webhook — which to use

See also