API Reference

Create Webhook

Register a webhook endpoint for the active organisation. The response includes a one-time signing secret used to verify HMAC signatures on every delivery — store it securely; the platform will not return it again.

POST/org/webhooks

Authentication

Accepts a JWT bearer token (Authorization: Bearer eyJ…) or an API key (X-API-Key: ms_live_…). API-key callers should send X-Project-ID unless the key is project-locked. Cross-tenant operators must send X-Tenant-ID.

Request body

Field	Type	Required	Description
`url`	`string`	required	HTTPS endpoint that receives deliveries.
`event_types`	`string[]`	required	e.g. `memory.created`, `integration.synced`, `billing.invoice.paid`.
`description`	`string`	optional	Free-form label.
`active`	`boolean`	optional	Default `true`.

request.json

{
  "url": "https://hooks.acme.io/memorysync",
  "event_types": [
    "memory.created",
    "memory.forgotten"
  ]
}

Response

Returns 200 OK with the following body.

Field	Type	Required	Description
`id`	`string`	optional	Endpoint id.
`url`	`string`	optional	Echoed delivery URL.
`event_types`	`string[]`	optional	Subscribed events.
`active`	`boolean`	optional	Whether deliveries are enabled.
`secret`	`string`	optional	One-time HMAC signing secret. Store this.
`created_at`	`string`	optional	RFC 3339 UTC.

200.json

{
  "id": "whk_01HX...",
  "url": "https://hooks.acme.io/memorysync",
  "event_types": [
    "memory.created",
    "memory.forgotten"
  ],
  "active": true,
  "secret": "whsec_aA9...",
  "created_at": "2026-05-04T12:30:11Z"
}

Errors

Status	Code	Description
400	`validation_error`	Body or query failed schema validation. The error includes the offending `field` name.
401	`unauthenticated`	Missing or invalid bearer token / API key.
403	`forbidden`	Authenticated principal lacks the required scope, role, or project access.
404	`not_found`	Target resource does not exist or is not visible to the calling tenant.
429	`rate_limited`	Per-IP or per-route limit exceeded. Respect the `Retry-After` header.
500	`internal_error`	Unhandled server error. Quote the `request_id` when contacting support.

Examples

cURL

curl -X POST https://api.memorysync.io/org/webhooks \
  -H "Authorization: Bearer $MEMORYSYNC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.acme.io/memorysync",
  "event_types": [
    "memory.created",
    "memory.forgotten"
  ]
}'

javascript

import { MemorySync } from 'memorysync'

const client = new MemorySync({ apiKey: process.env.MEMORYSYNC_KEY })

const result = await client.request({
  method: 'POST',
  path: '/org/webhooks',
  body: {
    "url": "https://hooks.acme.io/memorysync",
    "event_types": [
      "memory.created",
      "memory.forgotten"
    ]
  },
})
console.log(result)

python

from memorysync import Client

client = Client(api_key=os.environ["MEMORYSYNC_KEY"])

result = client.request(
    method="POST",
    path="/org/webhooks",
    json={
      "url": "https://hooks.acme.io/memorysync",
      "event_types": [
        "memory.created",
        "memory.forgotten"
      ]
    },
)
print(result)

Behavior & notes

Verify deliveries with the X-MemorySync-Signature header (HMAC-SHA256 over the raw body, hex-encoded). The secret is shown only at creation; rotate via POST /org/webhooks/{id}/rotate-secret. Failing endpoints back off automatically and auto-pause after 24h of consecutive failure.

← Previous

Archive / Unarchive

List Webhooks