Webhooks overview

Register HTTPS endpoints to receive event notifications when memories in your org are created, updated, or deleted. Useful for syncing mnueron memories into your own database, triggering downstream workflows, or analytics pipelines.

Events emitted

Register an endpoint

curl -X POST https://mnueron.com/api/webhooks \
  -H "Authorization: Bearer mnu_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/mnueron",
    "events": ["memory.saved", "memory.updated"],
    "description": "Sync to internal CRM"
  }'

Response includes a secret (64-char hex) shown once. Use it to verify incoming webhook signatures. Store it in your secrets manager immediately.

Payload format

{
  "delivery_id": "<uuid>",
  "event": "memory.saved",
  "delivered_at": 1700000000000,
  "payload": {
    "memory": {
      "id": "<uuid>",
      "namespace": "user-123",
      "tags": ["captured", "claude"],
      "source": "claude-backfill",
      "source_ref": "https://claude.ai/chat/...",
      "metadata": { ... },
      "created_at": 1700000000000
    }
  }
}

Note: content is NOT included by default. If you need it, GET the memory via its id using your API token. This keeps payloads small and avoids accidental leakage to subscribers.

Verifying signatures

Every delivery has an X-Mnueron-Signature header in the form sha256=<hex>. Compute HMAC-SHA256 of the raw request body with the endpoint's secret — compare to the signature value:

import hmac, hashlib

def is_valid(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    # constant-time compare
    return hmac.compare_digest(expected, header)

Other headers

• X-Mnueron-Event — event name (also in payload)
• X-Mnueron-Delivery — unique uuid for this delivery (also in payload)
• User-Agent — mnueron-webhook/1.0

Reliability

• 5-second delivery timeout per attempt.
• One immediate delivery, no automatic retries in v1. (Retry-with-backoff is a v0.3.2 enhancement.)
• After 20 consecutive failures, the endpoint is auto-disabled. Re-enable via PUT /api/webhooks/:id { enabled: true } once your receiver is healthy.
• Every delivery — success or failure — gets a row in webhook_deliveries retained for 30 days. Query the latest 100: GET /api/webhooks/:id/deliveries (coming v0.3.2).

Disable / delete

# pause without deleting
curl -X PUT -H "Authorization: Bearer mnu_..." -d '{"enabled":false}' \
  https://mnueron.com/api/webhooks/<id>

# permanent delete
curl -X DELETE -H "Authorization: Bearer mnu_..." \
  https://mnueron.com/api/webhooks/<id>