Hooks

How do I create a hook?

Use POST /api/memories/{id}/hooks with a name and delivery mode. Hooks deliver events as CDC log entries (polled by consumers) or as HTTP webhook callbacks to a registered URL.

Hooks are the change data capture layer of the Areev context database. They let external systems react in real time to writes, deletions, supersessions, and erasure events. CDC mode appends events to an internal log that consumers poll at their own pace. Webhook mode sends HTTP POST requests to a URL you configure, with optional HMAC-SHA256 signing for payload verification.

When you create a hook with generate_secret: true, the response includes an HMAC signing secret. Store this securely — it is returned only once and is used to verify that incoming AI memory webhook payloads are authentic. The response also returns the hook’s id and full configuration.

POST /api/memories/customer-support/hooks
Content-Type: application/json

{
  "name": "sync-to-warehouse",
  "delivery_mode": "webhook",
  "url": "https://example.com/hooks/areev",
  "event_filters": ["grain_created", "grain_superseded"],
  "generate_secret": true
}

What events can hooks capture?

Hooks filter on five event types that cover all write operations in the memory lifecycle.

These events represent every mutation that can occur in an AI agent memory instance: grain creation (via add, batch-add, or ingest), grain deletion (forget), grain replacement (supersede), cryptographic erasure (user or scope level), and key rotation. An empty event_filters array captures all event types — use this for full audit trails.

Each event payload includes the event_type, timestamp_ms, and context-specific fields like hash, grain_type, namespace, subject, relation, object, and user_id. CDC events include sequence numbers for ordered consumption.

POST /api/memories/customer-support/hooks
Content-Type: application/json

{
  "name": "audit-all-writes",
  "delivery_mode": "cdc",
  "event_filters": []
}

How does redaction control what hooks expose?

Configure redaction_mode to control how much grain data appears in hook payloads. This is critical when webhook URLs point to external systems where PII exposure is a concern.

Three redaction levels are available: full (default) includes all grain fields in the payload, metadata_only strips field content and sends only hash, grain type, namespace, and timestamp, and hash_only sends just the grain hash and event type. Choose the level that matches your external system’s data classification requirements.

When using full mode with a compliance policy that detects PII, you must set acknowledge_pii_risk: true to explicitly confirm that sending full grain content to external systems is acceptable (COMP-H1). This prevents accidental PII leakage through webhook integrations.

POST /api/memories/customer-support/hooks
Content-Type: application/json

{
  "name": "external-sync",
  "delivery_mode": "webhook",
  "url": "https://partner.example.com/webhook",
  "redaction_mode": "metadata_only",
  "event_filters": ["grain_created"]
}

How do I manage and verify hooks?

List all hooks with GET /api/memories/{id}/hooks and delete a hook with DELETE /api/memories/{id}/hooks/{hook_id}. Delete is idempotent — it returns HTTP 200 even if the hook does not exist.

Webhook hooks deliver HTTP POST requests signed with HMAC-SHA256 via the X-Areev-Signature header. To verify a payload: compute HMAC-SHA256(secret, request_body) and compare with the header value. Reject the request if they do not match. Failed deliveries are retried with exponential backoff up to a configured maximum.

CDC hooks include automatic log compaction to prevent unbounded storage growth. The list endpoint returns all registered hooks with their configuration, delivery mode, event filters, and redaction settings.

GET /api/memories/customer-support/hooks

DELETE /api/memories/customer-support/hooks/hook-abc123

Related

• Add and Query — operations that trigger hook events
• Supersede — grain_superseded events
• Forgetting — grain_forgotten and crypto_erase events