Gareth Wilson Gareth Wilson

Guide to Memos Webhooks: Features and Best Practices

Published


Memos is an open-source note-taking app that you host yourself. Its webhooks let other systems follow what you write: when a memo is created, edited, deleted or commented on, Memos posts a JSON event to your URLs. People use them to mirror notes into a search index or backup, post new memos to a chat channel, or run a script on every update.

What are Memos webhooks?

Webhooks in Memos belong to a user. Each user adds their own on the Settings page and receives events about memo activity. Because Memos is self-hosted, the requests come from your own server, and the instance's version decides which features you have.

Since version 0.31, a webhook with a signing secret is signed in the Standard Webhooks format, with webhook-id, webhook-timestamp and webhook-signature headers. Memos also has an unusual response contract: your endpoint must reply with a JSON body whose code is 0, or Memos counts the delivery as failed.

Memos webhook features

FeatureDetails
ConfigurationPer user, on the Settings page
FilteringNone. Every webhook receives every memo event
SignatureStandard Webhooks HMAC-SHA256 (0.31 and later, when a secret is set)
Signature headerwebhook-signature
SecretPer webhook, whsec_ plus 32 random bytes in base64, revealable in the edit dialog
BodyJSON
Event routingBody field activityType
Success response2xx with JSON {"code":0}
RetriesNone documented
Private targetsRefused unless allowlisted

Events and payloads

The documentation describes four dispatch points but doesn't print the activityType strings. The values below are the ones Memos v0.31.0's source code passes, so they could change between releases:

Event (activityType)Triggered WhenCommon Use Cases
memos.memo.createdA memo is createdSync new notes to a search index, chat channel or backup
memos.memo.updatedA memo is updatedRefresh a copy, re-run a classifier
memos.memo.deletedA memo is deletedRemove the mirrored copy
memos.memo.comment.createdA comment is added to a memoNotify the memo owner, thread the conversation elsewhere

The body has four top-level fields:

FieldMeaning
urlThe destination URL the webhook was sent to (in the v0.31.0 struct; not named in the docs)
activityTypeThe event name. Route on this
creatorWho the event is about
memoThe affected memo. Comment-created payloads include the parent relation so you can identify the conversation

Memos publishes no example body, and the docs don't describe the fields inside creator or memo. memo follows the API's Memo message, so read it with the API reference in hand and log a real delivery before you depend on a field. There's no event ID either; use the webhook-id header, which starts with msg_.

Setting up Memos webhooks

You need Memos 0.31 or later for signed deliveries.

  1. Open Settings in your Memos instance and add a webhook with your endpoint URL. It must use http or https and must resolve when you save it.
  2. Copy the signing secret shown when the webhook is created into MEMOS_WEBHOOK_SECRET, prefix included. You can reveal it again later from the webhook's edit dialog.
  3. For a webhook created before signing existed, open its edit dialog and generate a secret. Until you do, it sends no webhook-* headers.

Memos refuses targets that resolve to loopback, RFC 1918, link-local or IPv6 local addresses, to protect the instance from server-side request forgery. To deliver to an internal service, list exactly the hosts you need:

export MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST="hooks.internal.example,10.0.0.8,10.20.0.0/24"

Entries are exact hostnames, IP addresses or CIDRs; hostnames aren't wildcards. The same list can be passed with --webhook-private-network-allowlist.

A Hookdeck source URL is public, so it needs no allowlist entry. Create a source with the Memos type, then follow the configuration Hookdeck gives for it:

Generate a signing secret in the Memos webhook edit dialog and use it as the source's verification secret; older webhooks are unsigned until you do. Memos treats any response without the JSON body {"code":0} as failed, so configure the Hookdeck source to return a custom response with body {"code":0}.

Register the source URL as the webhook and forward it to your machine with the Hookdeck CLI:

npx hookdeck-cli listen 3000 memos --path /webhooks/memos

Create a memo, and check that the event arrives and that Memos doesn't mark it failed.

Securing Memos webhooks

Memos' docs give the standard steps: remove whsec_, base64-decode the rest, sign <webhook-id>.<webhook-timestamp>.<raw body> with HMAC-SHA256, base64-encode, and compare with each v1, entry. The v0.31.0 sender goes one step further and uses a secret without the whsec_ prefix as raw bytes. This function does both, the same way Hookdeck's Memos source does:

const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = secret.startsWith('whsec_')
    ? decodeBase64(secret.slice(6)) : Buffer.from(secret, 'utf8');
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Don't pass a secret without the prefix to a Standard Webhooks SDK, which always base64-decodes.

Memos tells you to reject timestamps outside "a small tolerance window" without naming one. Hookdeck has no tolerance, and its retries and replays carry the original webhook-timestamp, so behind Hookdeck any window rejects legitimate late deliveries. The verifier above checks only the signature.

The receiver has to answer with {"code":0}, not just a status:

const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

// noteSync.enqueue(messageId, event) stores the event and resolves once it is durable.
function createMemosReceiver(noteSync) {
  const app = express();
  app.post('/webhooks/memos', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.MEMOS_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    const event = parseJsonObject(req.body);
    if (!event) return res.sendStatus(400); // signed, but not a JSON object
    try {
      await noteSync.enqueue(req.headers['webhook-id'], event);
    } catch {
      return res.sendStatus(503);
    }
    return res.status(200).json({ code: 0 }); // an empty 200 counts as a failure
  });
  return app;
}

A Hookdeck Memos source accepts every request, including ones whose signature fails, and records those as failed verification without forwarding them. If you keep an older webhook unsigned on purpose, leave verification off on its source, since those requests have no signature to check.

Make Memos webhooks production-ready. Hookdeck Event Gateway answers Memos with {"code":0} straight away and retries your service, which Memos itself doesn't do.

Memos webhook limitations and pain points

No retries

The Problem: Memos created while your endpoint was down never reach it.

Why It Happens: Memos documents no retry policy. The v0.31.0 sender posts each event once from an async queue, with a 30-second timeout, and drops dispatches if the queue is full.

Workarounds:

  • Keep the receiver up and quick, and reconcile from the Memos API after downtime.

How Hookdeck Can Help: Hookdeck receives each event once and then retries delivery to your service until it succeeds, which gives Memos webhooks the retry layer they lack.

An empty 200 is a failure

The Problem: Your endpoint returns 200, yet Memos reports every delivery as failed.

Why It Happens: Memos requires a JSON body with code set to 0. Non-2xx responses, invalid JSON and nonzero codes all fail.

Workarounds:

  • Return {"code":0} from your handler.

How Hookdeck Can Help: Configure a custom response with body {"code":0} on the Hookdeck source, and your services can return whatever suits them.

Older webhooks are unsigned

The Problem: Deliveries from one webhook have no signature headers.

Why It Happens: Webhooks created before 0.31 signing have no secret until you generate one.

Workarounds:

  • Generate a secret in the webhook's edit dialog and update the receiver.

How Hookdeck Can Help: You can keep verification off on a source for an unsigned webhook and still get Hookdeck's history and retries, then turn it on once the secret exists.

Event names and payloads aren't documented

The Problem: A Memos upgrade could change what your handler receives.

Why It Happens: The activityType values come from the source code, not the docs, and there's no published example body.

Workarounds:

  • Acknowledge unknown activityType values with {"code":0} and log them.
  • Read the release notes before upgrading your instance.

How Hookdeck Can Help: Hookdeck keeps every real payload, so you can compare bodies before and after an upgrade.

Best practices

Deduplicate on webhook-id

Without an event ID in the body, the header is your key; the webhook idempotency guide has storage patterns.

Treat memos.memo.updated as a full replacement

The event carries the memo object, not a list of changes. Replace your stored copy with it.

Respect memo visibility

The payload contains the memo itself. If you mirror memos elsewhere, check the memo's visibility before publishing private notes.

Keep the allowlist tight

Add only the internal hosts you need to MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST. It exists to block server-side request forgery.

Conclusion

Memos' webhooks are self-hosted and simple, signed with Standard Webhooks from 0.31 and expecting a {"code":0} reply. Memos doesn't retry, so a failed delivery is gone unless something in front of your app keeps it.

Hookdeck Event Gateway answers Memos correctly and adds the retries and history Memos leaves out. Set up Hookdeck for free.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.