API reference
Doorbells
Receive signed webhook pings, then read the inbox for the changes.
On this page
Doorbells
Rather than poll the inbox, register a doorbell: an https URL we POST a small ping to when a page this key watches is revised by someone else. PUT /api/v1/doorbell with {"url": "https://…"} registers one and returns a signing secret, shown once — record it. GET describes it (never the secret), DELETE removes it.
The ping is content-free. Its body is exactly:
{"type": "inbox", "key": "fmrl_ab12", "at": "2026-09-22T15:04:05Z"}
key is your key's prefix, at an RFC 3339 timestamp. There is no page id, title, or revision content — all a ping says is that some page you watch changed. Read GET /api/v1/inbox for what: the feed is the truth, so a missed doorbell is fine — a doorbell only saves you polling.
Each POST is signed with the header Fmrl-Signature: t=<unix>,v1=<hex>, where <hex> is the HMAC-SHA256, under your secret, of <t> + "." + <raw body>. To verify: split on the comma, recompute the HMAC over t, a literal ., and the exact request body, and compare in constant time; reject a stale t.
Delivery is https-only and best-effort: no redirects are followed, the timeout is 5 seconds, pings coalesce to one per key per minute, and the destination is refused (see below) both when you register and again at delivery time. A doorbell holds a lease: any authenticated call to the API renews it, and a doorbell not renewed within the idle window (60 minutes by default) is treated as inactive at delivery time. Five consecutive delivery failures lapse the lease (active becomes false); the doorbell stays registered, and the next authenticated call (any route, including GET /api/v1/doorbell) revives it.
The URL must be https, have a public host (a loopback, private, link-local, CGNAT, or cloud-metadata address is refused), and not use port 25. A URL that fails any of these is 400 bad_request, naming the reason.
Register a doorbell
PUT /api/v1/doorbell
Registers or replaces this key's doorbell. Body: {"url": "https://…"}. A fresh signing secret is minted and returned once.
200 {"url": "https://…", "active": true, "created_at": "…", "renewed_at": "…", "secret": "…"}
A url that is not https, has no public host, or uses port 25 is 400 bad_request, naming the reason. See Doorbells above for the ping body and how to verify Fmrl-Signature.
Describe this key's doorbell
GET /api/v1/doorbell
Describes this key's doorbell, without the secret. 404 not_found when the key has none.
200 {"url": "https://…", "active": true, "created_at": "…", "renewed_at": "…"}
Remove this key's doorbell
DELETE /api/v1/doorbell
Removes this key's doorbell. 204 whether or not one was registered.