Webhooks

Webhooks deliver real-time event notifications to your HTTPS endpoint when things happen in your Memsolus workspace — memories created, processed, or the knowledge base updated.

Webhooks require the hasWebhooks entitlement on your plan.

Endpoint Overview

Method	Path	Permission	Description
POST	/v1/webhooks	webhook.write	Create a webhook
GET	/v1/webhooks	webhook.read	List webhooks
GET	/v1/webhooks/:id	webhook.read	Get webhook details
PUT	/v1/webhooks/:id	webhook.write	Update webhook
DELETE	/v1/webhooks/:id	webhook.delete	Delete webhook
POST	/v1/webhooks/:id/test	webhook.write	Send a test event
GET	/v1/webhooks/:id/deliveries	webhook.read	List delivery attempts
GET	/v1/webhooks/:id/deliveries/:deliveryId	webhook.read	Get a single delivery detail

---

Webhook Object

Field	Type	Description
id	string	UUID of the webhook
url	string	HTTPS delivery URL
events	string[]	Subscribed event types
description	string | null	Optional label
headers	object | null	Additional headers sent with each delivery
active	boolean	Whether the webhook is enabled
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-update timestamp

---

Create Webhook

POST/v1/webhooks

API Key

Create a new webhook endpoint

Parameter	Type	Description
urlrequired	string	HTTPS URL to receive webhook deliveries (max 2048 chars)
eventsrequired	string[]	List of event types to subscribe to (1–20 items). Use `*` to subscribe to all events. Format: `category.action` (e.g., `memory.created`)
description	string	Optional label for this webhook (max 255 chars)
headers	object	Additional headers sent with every delivery — max 10 key-value pairs
active	boolean	Whether the webhook is active (default: true)

curl -X POST https://api.memsolus.com/v1/webhooks \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-service.com/hooks/memsolus",
    "events": ["memory.created", "memory.updated", "knowledge.updated"],
    "description": "Production CRM integration",
    "active": true
  }'

201Webhook created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-service.com/hooks/memsolus",
  "events": ["memory.created", "memory.updated", "knowledge.updated"],
  "description": "Production CRM integration",
  "headers": null,
  "active": true,
  "secret": "whs_live_...",
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:30:00.000Z"
}

The secret field is returned only once at creation time. Store it securely — it is required to verify webhook signatures. It cannot be retrieved later.

Error code	Description
409 DUPLICATE_WEBHOOK_URL	A webhook for this URL already exists
422 WEBHOOK_LIMIT_EXCEEDED	Maximum webhook count reached for this plan

---

List Webhooks

GET/v1/webhooks

API Key

List all webhooks in the workspace

curl https://api.memsolus.com/v1/webhooks \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://your-service.com/hooks/memsolus",
      "events": ["memory.created", "knowledge.updated"],
      "description": "Production CRM integration",
      "headers": null,
      "active": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

---

Get Webhook

GET/v1/webhooks/:id

API Key

Get details of a webhook (secret not included)

curl https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-service.com/hooks/memsolus",
  "events": ["memory.created", "knowledge.updated"],
  "description": "Production CRM integration",
  "headers": { "X-Custom-Source": "memsolus" },
  "active": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:30:00.000Z"
}

---

Update Webhook

PUT/v1/webhooks/:id

API Key

Update webhook URL, events, headers, or status

Parameter	Type	Description
url	string	New delivery URL
events	string[]	Replace the subscribed event list
description	string	Updated description
headers	object	Replace additional headers (max 10 pairs)
active	boolean	Enable or disable the webhook

curl -X PUT https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["memory.created", "memory.updated", "knowledge.updated"],
    "active": true
  }'

200Webhook updated

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-service.com/hooks/memsolus",
  "events": ["memory.created", "memory.updated", "knowledge.updated"],
  "active": true,
  "updated_at": "2026-01-15T11:00:00.000Z"
}

---

Delete Webhook

DELETE/v1/webhooks/:id

API Key

Delete a webhook

curl -X DELETE https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..."

204Webhook deleted — no response body

---

Send Test Event

POST/v1/webhooks/:id/test

API Key

Trigger a test delivery to verify the endpoint

curl -X POST https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/test \
  -H "X-Api-Key: msk_live_..."

200Test event enqueued

{
  "eventId": "evt-uuid-here"
}

---

List Deliveries

GET/v1/webhooks/:id/deliveries

API Key

List delivery attempts for a webhook

Parameter	Type	Description
page	number	Page number (default: 1)
page_size	number	Results per page, max 100 (default: 20)

curl "https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/deliveries" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "del-uuid-1",
      "webhook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event": "memory.created",
      "status_code": 200,
      "success": true,
      "attempt": 1,
      "delivered_at": "2026-01-15T10:31:00.000Z"
    },
    {
      "id": "del-uuid-2",
      "webhook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event": "memory.updated",
      "status_code": 503,
      "success": false,
      "attempt": 3,
      "delivered_at": "2026-01-15T10:45:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

---

Get Delivery

GET/v1/webhooks/:id/deliveries/:deliveryId

API Key

Get the full details of a single delivery attempt

curl "https://api.memsolus.com/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/deliveries/del-uuid-1" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "id": "del-uuid-1",
  "webhook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "memory.created",
  "payload": {
    "event": "memory.created",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "data": {
      "id": "mem-uuid-here",
      "memory": "The user prefers dark mode.",
      "user_id": "user-123",
      "status": "PENDING"
    }
  },
  "status_code": 200,
  "response_body": "OK",
  "success": true,
  "attempt": 1,
  "duration_ms": 143,
  "delivered_at": "2026-01-15T10:31:00.000Z"
}

---

Webhook Payloads

Every delivery includes two verification headers:

X-Webhook-Signature: sha256=<hmac-hex>
X-Webhook-Timestamp: 1717200000

Verify the Signature

Always verify the signature before processing a delivery:

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(
  secret: string,
  payload: string,
  signatureHeader: string,
): boolean {
  const expected = createHmac('sha256', secret).update(payload).digest('hex');
  const received = signatureHeader.replace('sha256=', '');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Example Payload

{
  "event": "memory.created",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "memory": "The user prefers dark mode.",
    "user_id": "user-123",
    "status": "PENDING"
  }
}

---

Available Events

Event	Description
memory.created	A new memory was stored
memory.updated	Memory content or priority changed
memory.consolidated	Memory was evaluated against similar memories
knowledge.updated	The knowledge base was recompiled for a user
*	Subscribe to all events

---

Delivery Retries

Failed deliveries are retried with exponential backoff up to 5 times over 24 hours. Your endpoint must return a 2xx status code within 10 seconds to be considered successful.

---

API Overview

Authentication, permissions, and error codes

→

Memories

Events are triggered by memory operations

→