Module subscriptions 

v0.6.0.0 — webhook subscriptions.

Subscribers register a URL + shared secret + event/namespace/agent filters. When a matching event fires (e.g. memory_store), a fire-and-forget thread POSTs an HMAC-SHA256-signed JSON payload.

SSRF hardening:

• http:// only to 127.0.0.0/8 or localhost hosts; everywhere else requires https://
• RFC1918 / RFC4193 / link-local hosts are rejected unless allow_private_networks = true in the daemon config

Signature:

• Header X-Ai-Memory-Signature: sha256=<hex> over the raw JSON body
• The secret stored in the DB is a SHA-256 of the plaintext shared secret; the plaintext is returned once at subscription time and never leaves the DB after.

Structs

ConsolidatedEventDetails

memory_consolidated event — fires after db::consolidate commits. The outer memory_id carries the new consolidated memory’s id; source_ids is the array of memories that were merged (and deleted by the consolidate op).

DeleteEventDetails

memory_delete event — fires after the row is removed from memories. title and tier come from the pre-delete snapshot so subscribers can write meaningful audit entries without a roundtrip.

LinkCreatedEventDetails

memory_link_created event — fires after db::create_link commits. The outer memory_id carries the source id (the link-author side); target_id is the destination of the directed link.

NewSubscription

Parameters for creating a subscription.

PromoteEventDetails

memory_promote event — fires after a tier or vertical promotion commits. to_namespace is Some for vertical (memory_promote with a to_namespace argument); for the default tier promotion it is None and tier is set to the new tier ("long").

Subscription

Public-facing subscription record (no secret plaintext).

Constants

WEBHOOK_EVENT_TYPES

Canonical list of webhook lifecycle events surfaced to subscribers and to memory_capabilities (capabilities v2 webhook_events). Keep stable: integrators pin against these strings.

Functions

delete

Delete a subscription by id. Returns true if a row was removed.

dispatch_event

Fire an event to all matching subscribers. Each dispatch runs in its own OS thread and does NOT block the caller. Errors are logged and counted in the DB via failure_count.

dispatch_event_with_details

P5 (G9): full lifecycle dispatch with optional event-specific details. The details JSON is FLATTENED into the dispatch payload — keys must not collide with the outer envelope (event, memory_id, namespace, agent_id, delivered_at). The four new event types (memory_promote, memory_delete, memory_link_created, memory_consolidated) supply their *EventDetails struct serialised via serde_json::to_value.

insert

Insert a subscription, hashing any secret before persisting.

list

List all active subscriptions.

list_by_event

P5 (G9): list subscriptions matching a specific event type. Returns rows where either:

validate_url

SSRF guard. Rejects URLs that would cause the daemon to connect to private-range addresses, link-local, loopback (except explicitly), or non-HTTPS remote hosts.

validate_url_dns

SSRF guard with DNS resolution (#301 item 2). Resolves the host via the stdlib resolver and rejects if ANY returned SocketAddr’s IP is private / loopback / link-local. Guards against DNS-rebind attacks where an attacker-controlled hostname resolves to an internal IP at connect time.