Webhooks

Webhooks notify your service when memory in a workspace changes, so you can sync a search index, audit changes or trigger downstream work without polling.

EventsCopy Anchor Link

A subscription chooses any subset of add, update, delete and categorize. Internal derivations — facts promoted during consolidation, for example — do not emit one event each; consolidation emits a single categorize event per run.

Managing subscriptionsCopy Anchor Link

Subscriptions are per workspace and are managed in the web console under Webhooks:

• Create — give it a name, an HTTPS URL and the events. The signing secret (whsec_…) is shown once.
• Rotate secret — issues a new secret, shown once. For 24 hours afterwards every delivery is signed with both the new and the previous secret.
• Disable / enable — disabling pauses queued deliveries (they wait and are re-offered); enabling resumes them. Deleting a subscription discards its queued deliveries.
• Deliveries — every attempt with its status, HTTP code, response snippet and next retry.
• Requeue dead — re-queues deliveries that exhausted their retries (up to 100 per action), with the attempt counter reset.

The target URL must be HTTPS and resolve only to public IP addresses; loopback, private, link-local, CGNAT and cloud-metadata addresses are rejected. Creating webhooks requires a plan that includes them.

Delivery formatCopy Anchor Link

Each delivery is an HTTP POST with a JSON body and three headers:

{
  "version": "1",
  "event": "add",
  "eventId": "0d9c2a4e-7b31-4f8a-9c65-2e1d4b8a6f30",
  "memoryId": "8b0c1c0e-6c7d-4a51-9d2e-1f3a5b7c9d0e",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "workspaceId": "a1b2c3d4-e5f6-4a51-9d2e-0e02b2c3d479",
  "applicationId": null,
  "summary": "…",
  "occurredAt": "2026-08-31T12:34:56.789+00:00"
}

Verifying signaturesCopy Anchor Link

The signature is HMAC-SHA256(secret, "{t}.{rawBody}"), hex-encoded in lowercase, where t is the timestamp from the header. Use the entire secret string, including the whsec_ prefix, as the HMAC key.

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.AGENTMEMORY_WEBHOOK_SECRET // whsec_…
const TOLERANCE_SECONDS = 300
const seen = new Set() // use Redis or a database with a 24h TTL in production

app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-AgentMemory-Signature') ?? ''
  const match = /^t=(\d+)((?:,v1=[0-9a-f]{64})+)$/.exec(header)
  if (!match) return res.status(400).end()

  const t = match[1]
  const signatures = [...match[2].matchAll(/v1=([0-9a-f]{64})/g)].map(m => m[1])
  if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return res.status(400).end()

  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body.toString('utf8')}`).digest('hex')
  if (!signatures.some(s => crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(s))))
    return res.status(401).end()

  const deliveryId = req.get('X-AgentMemory-Delivery')
  if (seen.has(deliveryId)) return res.status(200).end()
  seen.add(deliveryId)

  const event = JSON.parse(req.body)
  if (event.version !== '1') return res.status(200).end() // unknown schema: acknowledge and log
  // handle event.event / event.memoryId
  res.status(200).end()
})

RetriesCopy Anchor Link

Any response other than 2xx — or a timeout or connection error — is a failed attempt. Deliveries are retried with backoff of roughly 1 minute, 5 minutes, 30 minutes and 2 hours (each delay varies by ±20%). After 5 attempts a delivery is marked dead and is not retried automatically; requeue it from the console once your endpoint is fixed.

Retries re-send the identical body with the same X-AgentMemory-Delivery ID and a fresh signature timestamp, so de-duplicating on the delivery ID (and on eventId across endpoints) makes processing exactly-once from your side.

The sender never follows redirects — answer the final URL directly — and connects only to the IP address it validated when resolving your hostname.

Self-hosting settingsCopy Anchor Link