# Memos Webhooks

[Memos](https://usememos.com) is an open-source, self-hosted note-taking app. Each user can add webhooks in **Settings**, and Memos POSTs a JSON event to the URL when a memo is created, updated, deleted or commented on. Since 0.31 deliveries are signed in the Standard Webhooks format (`webhook-id`, `webhook-timestamp`, `webhook-signature`) whenever the webhook has a signing secret.

## When to Use This Skill

* How do I receive Memos webhooks?
* How do I verify a Memos webhook signature (`webhook-signature`)?
* Where do I find my Memos webhook secret (`whsec_...`)?
* Why does Memos report my webhook as failed when I return `200 OK`?
* How do I handle `memos.memo.created`, `memos.memo.updated`, `memos.memo.deleted` or `memos.memo.comment.created` events?
* Why is my Memos webhook arriving unsigned, or failing verification only on retries and replays?

## Required Response and Configuration Alert

Memos treats any response that is not 2xx **with a JSON body whose `code` is `0`** as a failed delivery. A plain `200 OK` with an empty body fails. Every accepted delivery must be answered with HTTP 200 and `{"code":0}` (the examples do this). The Hookdeck configuration alert for this source reads:

> "Generate a signing secret in the Memos webhook edit dialog. Older webhooks are unsigned until you do. Memos treats any response without JSON {"code":0} as failed, so set a custom response with body {"code":0} on this source."

So if you receive through Hookdeck, set a custom response with body `{"code":0}` on the source. Signing is conditional: Memos only signs when the webhook has a secret. New webhooks get one; older webhooks are unsigned until you generate a secret in the edit dialog. Fail closed in your handler when `MEMOS_WEBHOOK_SECRET` is not set.

## Verification (core)

| Header | Value |
| --- | --- |
| `webhook-id` | Unique message ID beginning with `msg_`; retries reuse it. Your idempotency key (the body has no event id) |
| `webhook-timestamp` | Unix seconds |
| `webhook-signature` | One or more space-separated `v1,<base64>` entries |

Signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`, HMAC-SHA256, base64 output. For a `whsec_...` secret the key is the base64-**decoded** part after the prefix; Memos uses any other secret value as its raw bytes. Compare against every `v1,` entry and ignore other versions. If `webhook-id` is absent, read `svix-id`, `svix-timestamp` and `svix-signature` instead. The examples use the `standardwebhooks` library (npm and PyPI):

```javascript
const { Webhook } = require('standardwebhooks');

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyMemos(rawBody, headers, secret = process.env.MEMOS_WEBHOOK_SECRET) {
  const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
  const wh = secret.startsWith('whsec_')
    ? new Webhook(secret)
    : new Webhook(Buffer.from(secret, 'utf8'), { format: 'raw' }); // non-whsec_ secret = raw bytes
  wh.verify(rawBody, {
    'webhook-id': headers[`${p}-id`],
    'webhook-timestamp': headers[`${p}-timestamp`],
    'webhook-signature': headers[`${p}-signature`],
  }, { jsonParse: false }); // throws on a bad signature or stale timestamp → respond 401
}

```

The library always enforces a fixed **5-minute timestamp window**. Hookdeck retries and replays resend the original `webhook-timestamp`, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memos-webhooks/references/verification.md), which can drop or widen the window. In Express, read the body with `express.raw({ type: '*/*' })` so any content type verifies, and parse JSON only after the check.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memos-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memos-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memos-webhooks/examples/fastapi/).

## Event Type and Payload

Memos sends `Content-Type: application/json` with this body, and the event name is the top-level `activityType`:

```json
{
  "url": "https://example.com/webhooks/memos",
  "activityType": "memos.memo.created",
  "creator": "users/1",
  "memo": { "name": "memos/abc123", "content": "Hello from Memos" }
}

```

The docs name `activityType`, `creator` and the affected `memo` (comment-created payloads also include the parent relation); `url` is the destination URL. They do not list the `activityType` values or the fields inside `memo`: the values below are the strings the v0.31.0 dispatchers pass, and the `memo` fields in the sample are illustrative, so the examples read only `activityType` and `creator`.

## Common Event Types

| Event (`activityType`) | Fired when |
| --- | --- |
| `memos.memo.created` | A memo is created |
| `memos.memo.updated` | A memo is updated |
| `memos.memo.deleted` | A memo is deleted |
| `memos.memo.comment.created` | A comment is added to a memo |

These four are the events the docs describe (the list may not be exhaustive). Every webhook receives every memo event; there is no per-event selection. Acknowledge types you don't recognise with `{"code":0}` so Memos doesn't count a failure. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memos-webhooks/references/overview.md).

## Delivery Semantics

Return `2xx` with `{"code":0}` within 30 seconds (the v0.31.0 client timeout). A non-2xx status, invalid JSON or a nonzero `code` is a delivery failure. Deduplicate on `webhook-id`, and reject timestamps outside a window you choose. Return `400` for missing headers and `401` for a bad signature. Memos rejects private-network destinations by default; in 0.31 allow yours with `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST`. There is no handshake or challenge request.

## Environment Variables

```bash
MEMOS_WEBHOOK_SECRET=whsec_xxxxx   # full value, prefix included; handlers fail closed (500) without it

```

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 memos --path /webhooks/memos

```

Use the printed URL as the webhook URL in your Memos settings. Memos must be able to reach it, and the Hookdeck URL is public, so the private-network allowlist is not needed.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memos-webhooks/references/overview.md) - Events, payload and response contract
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memos-webhooks/references/setup.md) - Add a webhook, get the secret, set the `{"code":0}` response
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memos-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging