Agent skill
Memos Webhooks Skill
Receive and verify Memos (usememos.com) webhooks, which follow the Standard Webhooks specification when the webhook has a whsec_ signing secret. Use when setting up a Memos webhook endpoint, debugging webhook-id / webhook-timestamp / webhook-signature verification, replying with the required {"code":0} body, or handling memos.memo.created, memos.memo.updated, memos.memo.deleted and memos.memo.comment.created events.
Install this skill
npx skills add hookdeck/webhook-skills --skill memos-webhooks
Memos 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.deletedormemos.memo.comment.createdevents? - 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):
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, 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/, examples/nextjs/, examples/fastapi/.
Event Type and Payload
Memos sends Content-Type: application/json with this body, and the event name is the top-level activityType:
{
"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.
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_. There is no handshake or challenge request.
Environment Variables
MEMOS_WEBHOOK_SECRET=whsec_xxxxx # full value, prefix included; handlers fail closed (500) without it
Local Development
# 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 - Events, payload and response contract
- references/setup.md - Add a webhook, get the secret, set the
{"code":0}response - references/verification.md - Library and manual verification, gotchas, debugging