Webhooks
A webhook sends a signed POST to your URL when something happens in a library. Webhooks are part
of Pro. Manage them under Settings → API and webhooks or with the API (/v1/webhooks; a token or API
key needs bookmarks:read, plus the read scope of each event it subscribes to).
Events
| Event | data |
|---|---|
bookmark.created | { bookmark } |
bookmark.updated | { bookmark } (also sent with a restore and when a highlight changes the bookmark) |
bookmark.deleted | { id, permanent, bookmark } (bookmark is null once it is permanently gone) |
bookmark.restored | { bookmark } |
highlight.created | { highlight, bookmark } (private highlights go only to their author's webhooks) |
collection.bookmark_added | { collectionId, bookmark } |
tag.created | { tag: { id, name, createdAt } } |
bookmark has the same shape as GET /v1/bookmarks/:id. A webhook with a collectionId gets
bookmark and highlight events only for bookmarks in that collection (Zapier's "new bookmark in
collection" subscribes to collection.bookmark_added with one).
Every body looks like:
{ "id": "6f1c…", "event": "bookmark.created", "createdAt": "2026-11-13T12:00:00.000Z", "libraryId": "…", "data": { … } }
id is the delivery id; retries of a delivery send the same body, so use it to ignore duplicates.
Headers
| Header | Value |
|---|---|
X-Bkmark-Event | The event name (ping for a test send). |
X-Bkmark-Delivery | The delivery id (same as the body's id). |
X-Bkmark-Timestamp | Unix time, in seconds, when this attempt was signed. |
X-Bkmark-Signature | v1= followed by a lowercase hex HMAC-SHA256. |
Verifying a delivery
The secret (whsec_…) is shown once, when the webhook is created. To check a delivery:
- Read the raw request body, before any JSON parsing.
- Compute
HMAC-SHA256(secret, timestamp + "." + rawBody)as lowercase hex, wheretimestampis theX-Bkmark-Timestampheader andsecretis the wholewhsec_…string. - Compare
"v1=" + hexwithX-Bkmark-Signaturein constant time. - Reject the delivery if the timestamp is more than five minutes from your clock (replays).
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, headers, secret) {
const timestamp = headers['x-bkmark-timestamp'];
const expected = `v1=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`;
const given = headers['x-bkmark-signature'] ?? '';
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
Delivery, retries and turning off
- Answer with any
2xxwithin 10 seconds. Redirects are not followed. - A failed attempt is retried after about 1, 2, 4, 8 and 16 minutes (six attempts in all).
- After 10 deliveries in a row fail (each after all its retries), the webhook is turned off and its owner gets an email. Turning it back on clears the count.
- Answer
410 Goneto unsubscribe: the webhook is turned off at once, without retries. - URLs must be
httpsand must not resolve to a private or internal address (checked on every delivery, so a DNS change can't point a webhook inside our network). POST /v1/webhooks/:id/testsends a signedpingright away and returns the delivery.GET /v1/webhooks/:id/deliverieslists deliveries (body, status, response code, timing) for the last 30 days.- A webhook created through an OAuth app (such as Zapier) stops when that app is disconnected; one created with an API key is deleted with the key.