Skip to content
bkmark.it
Docs menu

API reference

Webhooks

Signed POSTs to your URL when something changes. Pro.

post /v1/webhooks

Subscribe a URL to library events (Pro). The signing secret is returned once.

Key or token with bookmarks:read Returns 201

Body

Body fields
NameTypeDescription
urlrequiredstringUp to 2,048 characters.
eventsrequiredenum[]Up to 7 items.
collectionIduuid
descriptionstringUp to 200 characters.

Example

curl -X POST 'https://api.bkmark.it/v1/webhooks' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","events":["bookmark.created"]}'
Response fields (13)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
urlrequiredstring
eventsrequiredenum[]
collectionIdrequireduuid or null
descriptionrequiredstring or null
activerequiredboolean
disabledReasonrequiredstring or null
consecutiveFailuresrequiredinteger-9007199254740991–9007199254740991.
lastDeliveryAtrequiredstring or null
createdAtrequiredstring
updatedAtrequiredstring
secretrequiredstring

get /v1/webhooks

Your webhooks in the library.

Key or token with bookmarks:read Returns 200

Example

curl 'https://api.bkmark.it/v1/webhooks' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (1)
Response fields
NameTypeDescription
datarequiredobject[]
idrequireduuid
libraryIdrequireduuid
urlrequiredstring
eventsrequiredenum[]
collectionIdrequireduuid or null
descriptionrequiredstring or null
activerequiredboolean
disabledReasonrequiredstring or null
consecutiveFailuresrequiredinteger-9007199254740991–9007199254740991.
lastDeliveryAtrequiredstring or null
createdAtrequiredstring
updatedAtrequiredstring

patch /v1/webhooks/{id}

Change a webhook, or turn it off and on (on clears its failure count).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
urlstringUp to 2,048 characters.
eventsenum[]Up to 7 items.
collectionIduuid or null
descriptionstring or nullUp to 200 characters.
activeboolean

Example

curl -X PATCH 'https://api.bkmark.it/v1/webhooks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","events":["bookmark.created"]}'
Response fields (12)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
urlrequiredstring
eventsrequiredenum[]
collectionIdrequireduuid or null
descriptionrequiredstring or null
activerequiredboolean
disabledReasonrequiredstring or null
consecutiveFailuresrequiredinteger-9007199254740991–9007199254740991.
lastDeliveryAtrequiredstring or null
createdAtrequiredstring
updatedAtrequiredstring

delete /v1/webhooks/{id}

Delete a webhook (Zapier unsubscribes here).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl -X DELETE 'https://api.bkmark.it/v1/webhooks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (1)
Response fields
NameTypeDescription
messagerequiredstring

get /v1/webhooks/{id}/deliveries

Recent deliveries, newest first (kept 30 days).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
cursoruuid
limitintegerDefault 25. 1–100.
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/webhooks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/deliveries' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (2)
Response fields
NameTypeDescription
datarequiredobject[]
idrequireduuid
eventrequiredstring
statusrequiredenumOne of pending, success, failed.
attemptsrequiredinteger-9007199254740991–9007199254740991.
responseStatusrequiredinteger or null-9007199254740991–9007199254740991.
errorrequiredstring or null
durationMsrequiredinteger or null-9007199254740991–9007199254740991.
deliveredAtrequiredstring or null
createdAtrequiredstring
payloadrequiredobject
nextCursorrequiredstring or null

post /v1/webhooks/{id}/test

Send a signed `ping` now and return the delivery (works while turned off).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl -X POST 'https://api.bkmark.it/v1/webhooks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/test' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (10)
Response fields
NameTypeDescription
idrequireduuid
eventrequiredstring
statusrequiredenumOne of pending, success, failed.
attemptsrequiredinteger-9007199254740991–9007199254740991.
responseStatusrequiredinteger or null-9007199254740991–9007199254740991.
errorrequiredstring or null
durationMsrequiredinteger or null-9007199254740991–9007199254740991.
deliveredAtrequiredstring or null
createdAtrequiredstring
payloadrequiredobject