Skip to content

Webhooks ​

A workspace can tell a URL of yours when something happens in it — a page created, a comment written — so that an integration does not have to poll for changes.

Pointing one at your endpoint ​

bash
curl -X POST https://notes.example.com/api/webhooks \
  -H 'content-type: application/json' -b "$YOUR_SESSION_COOKIE" \
  -d '{"url": "https://hooks.example.com/notesflow", "events": ["page.created", "comment.created"]}'
json
{
  "webhook": { "id": "…", "url": "https://hooks.example.com/notesflow", "events": ["page.created", "comment.created"] },
  "secret": "3hK…"
}

The signing secret is shown once. It is stored sealed with the deployment's key — not hashed, because we sign with it — the same way stored SSO client secrets are.

It takes the manage_webhooks capability. An API key cannot create or change webhooks, whatever it carries: arranging for a workspace's content to be sent somewhere else is a decision about who may read it, and a stolen credential should not be able to make it.

The URL has to be https, and may not point at the server's own machine or a private network: loopback, private and link-local addresses are refused when the webhook is made, and again at each delivery, where a name's address is actually known. Redirects are not followed. A deployment whose every workspace is its own can allow private addresses with NOTESFLOW_OUTBOUND_ALLOW_PRIVATE=1.

What arrives ​

http
POST /notesflow HTTP/1.1
content-type: application/json
x-notesflow-event: page.created
x-notesflow-delivery: 2b7c…
x-notesflow-signature: t=1789459200,v1=9f2b…

{"event":"page.created","workspaceId":"…","at":"2026-09-20T09:00:00Z","pageId":"…","title":"…","by":"…"}

Checking the signature ​

The signature covers the timestamp and the body, so a delivery captured off the wire cannot be replayed at you later:

js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, body, header) {
  const [, seconds, mac] = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header.trim()) ?? [];
  if (!mac) return false;
  if (Math.abs(Date.now() - Number(seconds) * 1000) > 5 * 60 * 1000) return false;

  const expected = createHmac('sha256', secret).update(`${seconds}.${body}`).digest('hex');
  return timingSafeEqual(Buffer.from(mac, 'hex'), Buffer.from(expected, 'hex'));
}

Verify against the raw body, before any JSON parsing: a re-serialised object is a different string, and its signature will not match.

Events ​

EventWhenEmitted today
page.createdA page is madeyes
page.trashedA page and its children go to the trashyes
comment.createdSomebody commentsyes
page.updatedA page is renamed, moved, archived or brought back, reverted, or merged intoyes
page.writtenThe text of a page changed, and the writing has stoppedyes
member.changedSomebody leaves, or their role changesyes
share.changedA page is shared or unsharedyes
digest.dailyOnce each morning: yesterday's busiest pages, who wrote there, and how many commentsyes

POST /api/webhooks/<id>/test queues a delivery whenever you want to see one arrive.

page.written is debounced, and the others are not. A paragraph typed at speed reaches the log many times over; an event for each would be describing keystrokes to somebody who asked about pages. So one is sent once the typing stops — five seconds by default, NOTESFLOW_WRITTEN_DEBOUNCE_MS to change it — and it says only which page. What changed is a question for the page itself, or for GET /api/pages/<id>/history.

page.updated and page.written are different questions: the first is about a page's place — its name, where it sits, what its properties say — and the second is about its text. Renaming and moving append no op, so nothing in the log would otherwise say either happened.

Neither member.changed nor share.changed carries an email address. An endpoint is somewhere outside this deployment, and who belongs here is not something to post to it; both name their subject by id, which a listener can ask about over the API if it may.

Posting to Mattermost or Slack ​

A Mattermost or Slack incoming webhook takes a message, not an event. Choose Mattermost messages or Slack messages when adding the webhook in the console (or send "format": "mattermost" or "format": "slack"), paste the incoming webhook's URL, and each event arrives in the channel as a sentence:

Ana created Deploy runbook. Bo commented on Capacity plan.

The same queue, retries and Send a test as any webhook — only the body differs.

What a channel sees. Everybody in a channel reads what is posted there, including people who may not be able to open the page. So a message names the page and who acted, with a link, and never what was written — no comment text, no page text. Opening the link is decided by the app's permissions as usual. A webhook covers the whole workspace, though, so its messages name pages anyone in the workspace wrote: point it at a channel no wider than the workspace, and pick its events with that in mind. page.written in a busy workspace is a lot of messages.

Titles are escaped, so a page named to look like a link or an @channel stays plain text. Each format is escaped in its own markup. Slack's has no escape character and links a bare address by itself, so in a Slack message an address or an @ in a title is broken up with an invisible space and stays words. A title written with *stars* can still show in bold there; it cannot link anywhere or notify anybody.

A daily digest ​

A channel that hears every event in a busy workspace is a channel people mute. Choose A daily digest when adding the webhook (or subscribe it to digest.daily alone) and it gets one message a morning instead:

Yesterday in Acme (2026-09-26): 12 pages written in, 5 comments.

The ten busiest pages by name, the rest as a count. Like every message it carries titles and names, never what was written, and a day with nothing written sends nothing.

It goes out from NOTESFLOW_DIGEST_HOUR (default 8) in NOTESFLOW_DIGEST_TZ (default UTC, any IANA zone such as Asia/Taipei), covering the calendar day before in that zone. It is sent once per day per webhook, however many servers run and however often they restart — the queue refuses a second one — and a server that was down at the hour sends when it comes back. In JSON format the payload is {date, timeZone, workspace, pages: [{pageId, title, people, written, edited}], morePages, comments}.

Retries ​

A delivery that fails is tried again after about a minute, then four minutes, a quarter of an hour, an hour, and four hours. After that it is left alone, with the last status and error kept against it.

bash
curl …/api/webhooks/<id>/deliveries -b "$COOKIE"

Anything other than a 2xx is a failure, as is a timeout — ten seconds. Nothing in the app ever waits on your endpoint: an event is written to a queue table by whoever caused it and sent from a worker, so a slow or dead endpoint can never hold up somebody's editing. The queue is a table rather than memory, so a restart mid-retry does not lose the event.

The worker runs every five seconds (NOTESFLOW_WEBHOOK_INTERVAL_MS).

Stopping one ​

bash
curl -X DELETE …/api/webhooks/<id> -b "$COOKIE"

It stops sending. Its delivery history is kept, because "did you ever send me that" is a question worth being able to answer.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.