Webhooks

Register an HTTPS endpoint to receive memory lifecycle events. Each delivery is signed with the webhook's secret using HMAC-SHA256 in the X-CortexDB-Signature header. Failed deliveries are retried with exponential backoff.

Supported event types:

| Event | Fired when | |---|---| | remember | A memory is stored (via /v1/remember or /v1/bulk-remember) | | forget | A /v1/forget operation completes | | episode | An episode is ingested (via /v1/episodes or a connector) |

POST /v1/webhooks

{
  "url": "https://hooks.example.com/cortexdb",
  "events": ["remember", "forget"],
  "secret": "whk_at_least_32_chars_of_random"
}

| Field | Type | Required | Description | |---|---|---|---| | url | string | Yes | HTTPS endpoint to POST events to | | events | string[] | Yes | Subset of supported events | | tenant_id | string | No | Sub-tenant scope | | secret | string | No | HMAC signing secret. If omitted, the server generates one and returns it once. |

Response (201 Created)

{
  "webhook_id": "01912a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "url": "https://hooks.example.com/cortexdb",
  "events": ["remember", "forget"]
}

GET /v1/webhooks

List registered webhooks for the authenticated tenant.

{
  "webhooks": [
    {
      "id": "01912a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
      "url": "https://hooks.example.com/cortexdb",
      "events": ["remember", "forget"],
      "tenant_id": "engineering"
    }
  ],
  "count": 1
}

The secret is not returned. It is only shown at creation time.

DELETE /v1/webhooks/:id

Deregister a webhook.

curl -X DELETE https://api.cortexdb.ai/v1/webhooks/01912a3b-… \
  -H "Authorization: Bearer your-api-key"

Returns { "deleted": true }.

Delivery format

Each event POST has these headers:

Content-Type: application/json
X-CortexDB-Event: remember
X-CortexDB-Delivery: 01912a3b-…-delivery
X-CortexDB-Signature: sha256=<hmac-sha256(body, secret)>

Body shape (example for remember):

{
  "event": "remember",
  "delivery_id": "01912a3b-…-delivery",
  "tenant_id": "engineering",
  "event_id": "01912a3b-…-evt",
  "content_preview": "Chose CockroachDB for the payments service.",
  "occurred_at": "2026-05-14T10:00:00Z"
}

Verify by HMAC-SHA256 of the raw request body with the secret, then compare to the X-CortexDB-Signature header (constant-time equality).