MemoryKit Docs

Receive real-time HTTP callbacks when memories finish processing, fail, or other events occur.

Webhooks let you receive HTTP callbacks when events happen in your project — no polling needed. Subscribe to events like memory.completed and MemoryKit will send a POST request to your endpoint.

Quick setup

Create your endpoint

Your server must accept POST requests and return 2xx within 10 seconds.

Register the webhook

Tell MemoryKit where to send events and which events you care about.

Verify signatures

Every delivery is signed with HMAC-SHA256 so you can verify it came from MemoryKit.

Register a webhook

const webhook = await mk.webhooks.create({
  url: "https://yourapp.com/webhooks/memorykit",
  events: ["memory.completed", "memory.failed"],
});
 
// Save this — it's only returned once
console.log("Secret:", webhook.secret);

The signing secret is only returned when you create the webhook. Store it securely — you'll need it to verify signatures.

Event types

Event	Description
`memory.completed`	Memory processing finished successfully
`memory.failed`	Memory processing failed
`*`	Subscribe to all current and future events

Signature verification

Every delivery includes two headers:

Header	Description
`X-MemoryKit-Signature`	HMAC-SHA256 hex digest of the request body
`X-MemoryKit-Event`	Event type (e.g., `memory.completed`)

import express from "express";
import crypto from "crypto";
 
const app = express();
 
// Use raw body for HMAC verification, then parse JSON
app.post(
  "/webhooks/memorykit",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-memorykit-signature"] as string;
    const rawBody = req.body as Buffer;
 
    const expected = crypto
      .createHmac("sha256", process.env.WEBHOOK_SECRET!)
      .update(rawBody)
      .digest("hex");
 
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).send("Invalid signature");
    }
 
    const payload = JSON.parse(rawBody.toString());
    const event = req.headers["x-memorykit-event"];
 
    switch (event) {
      case "memory.completed":
        console.log(`Memory ${payload.id} ready — ${payload.chunks_count} chunks`);
        break;
      case "memory.failed":
        console.error(`Memory ${payload.id} failed: ${payload.error}`);
        break;
    }
 
    res.status(200).send("OK");
  }
);

Test delivery

Send a test event to verify your endpoint is working:

const result = await mk.webhooks.test(webhook.id);
console.log("Test passed:", result.success);

Manage webhooks

// List all webhooks
const webhooks = await mk.webhooks.list();
 
// Delete a webhook
await mk.webhooks.delete("wh_abc123");

Retry behavior

If your endpoint returns a non-2xx status or times out (>10s), MemoryKit retries with exponential backoff:

Attempt	Delay
1st retry	~1 min
2nd retry	~5 min
3rd retry	~30 min

After repeated failures, the webhook's failure_count increases. After sustained failures, it may be automatically deactivated.

Check webhook.failure_count and webhook.active to monitor webhook health. Re-activate deactivated webhooks by creating a new one.

Webhooks

On this page