Webhooks

Memo fires HMAC-signed POSTs to any HTTPS endpoint you register whenever a subscribed event happens. The dispatcher is a cron-driven worker over a webhook_deliveries queue; failed deliveries retry with exponential backoff for up to 6 attempts.

Quick start#

1. Visit /<your-username>/settings/webhooks.
2. Click + New webhook, paste your receiver URL, tick at least one event, save.
3. The reveal modal shows your signing secret once. Copy it into your receiver.
4. Memo will POST to your URL the next time a subscribed event fires.

Event catalog#

Firing sites (REST ↔ MCP parity)#

Every mutation that has both a REST and an MCP entrypoint fires the same webhook from both. The dispatcher (fireWebhookEvent in src/lib/webhooks/store.ts) is called once per fire site; the cron worker handles delivery + retry uniformly. This table is the source of truth for which file emits which event.

Notes:

• 10 of the 11 events have a fire site; space.deleted is declared in WEBHOOK_EVENTS but not yet wired (the space DELETE handler does not emit it).
• link.created, link.updated, project.published, and version.rollback fire from both REST and MCP — this is the parity rule: an MCP client invoking update_link_full cannot bypass the webhook that the matching REST PATCH would have produced.
• visit.* and nda.signed are visitor-side and have no MCP equivalent (MCP is owner-only). link.expired is cron-only — no human-driven entrypoint.
• Payloads match between REST and MCP fire sites (same linkId / versionId / etc. fields). Receivers don't need a separate code path per source.

Delivery shape#

POST <your-url> HTTP/1.1
Host: …
content-type:        application/json
memo-event:          project.published
memo-delivery-id:    <uuid>
memo-endpoint-id:    <uuid>
memo-signature:      t=1717024811,v1=<hex hmac-sha256>

{
  "event": "project.published",
  "ts":    "2026-…",
  "data":  { … event-specific payload … }
}

Signature verification#

import { createHmac } from "node:crypto";

function verify(secret: string, header: string, body: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 min tolerance
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return parts.v1 === expected;
}

The tolerance window prevents replays. Receivers MUST verify both the signature and the timestamp.

Retry semantics#

• Initial delivery is attempted within ~30 s of the event firing.
• On non-2xx response: attempts are bumped, nextAttemptAt is set to now + 30s × 2^(attempts-1) (30 s, 1 m, 2 m, 4 m, 8 m, 16 m).
• After 6 failed attempts the delivery is marked exhausted and stops retrying. The row stays in webhook_deliveries for forensic inspection.
• The webhook_endpoints.last_delivery_at column updates only on success.

Surfaces#

Audit#

Every lifecycle action writes an audit_logs row:

The delivery log itself (webhook_deliveries) is the per-event audit; you can SELECT * FROM memo.webhook_deliveries ORDER BY created_at DESC to see every attempt for every endpoint.

Related observability surfaces#

Webhooks are one of three "watch this in near-real-time" mechanisms memo exposes. They're best for owner-side automation (Slack/Notion/internal CRM). For human-eyes-on the activity, see:

• Live activity feed — the Activity tab polls /api/owner/projects/<id>/activity/since every 8s and slides new rows in with a yellow-fade. No webhook receiver required; only works when the tab is open.
• People timeline — cross-link history per email at /u/<username>/people/<emailHash>.
• Behavioural signals — skim / deep_read / return / share_detected chips on Activity / People rows.

The engagementScore and sectionsEntered fields in the visit.completed payload mirror the columns / Mongo events the Activity surfaces use, so a webhook receiver can build its own dashboard that matches memo's view of "hottest leads" exactly.

Threat model#