Skip to content
bkmark.it
Docs menu

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

Eventdata
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

HeaderValue
X-Bkmark-EventThe event name (ping for a test send).
X-Bkmark-DeliveryThe delivery id (same as the body's id).
X-Bkmark-TimestampUnix time, in seconds, when this attempt was signed.
X-Bkmark-Signaturev1= 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:

  1. Read the raw request body, before any JSON parsing.
  2. Compute HMAC-SHA256(secret, timestamp + "." + rawBody) as lowercase hex, where timestamp is the X-Bkmark-Timestamp header and secret is the whole whsec_… string.
  3. Compare "v1=" + hex with X-Bkmark-Signature in constant time.
  4. 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 2xx within 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 Gone to unsubscribe: the webhook is turned off at once, without retries.
  • URLs must be https and 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/test sends a signed ping right away and returns the delivery.
  • GET /v1/webhooks/:id/deliveries lists 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.