Webhooks
Signed POSTs to your URL when something changes. Pro.
- post /v1/webhooks
- get /v1/webhooks
- patch /v1/webhooks/{id}
- delete /v1/webhooks/{id}
- get /v1/webhooks/{id}/deliveries
- post /v1/webhooks/{id}/test
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
| Name | Type | Description |
|---|---|---|
urlrequired | string | Up to 2,048 characters. |
eventsrequired | enum[] | Up to 7 items. |
collectionId | uuid | |
description | string | Up 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)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
urlrequired | string | |
eventsrequired | enum[] | |
collectionIdrequired | uuid or null | |
descriptionrequired | string or null | |
activerequired | boolean | |
disabledReasonrequired | string or null | |
consecutiveFailuresrequired | integer | -9007199254740991–9007199254740991. |
lastDeliveryAtrequired | string or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
secretrequired | string |
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)
| Name | Type | Description |
|---|---|---|
datarequired | object[] | |
idrequired | uuid | |
libraryIdrequired | uuid | |
urlrequired | string | |
eventsrequired | enum[] | |
collectionIdrequired | uuid or null | |
descriptionrequired | string or null | |
activerequired | boolean | |
disabledReasonrequired | string or null | |
consecutiveFailuresrequired | integer | -9007199254740991–9007199254740991. |
lastDeliveryAtrequired | string or null | |
createdAtrequired | string | |
updatedAtrequired | string |
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
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
url | string | Up to 2,048 characters. |
events | enum[] | Up to 7 items. |
collectionId | uuid or null | |
description | string or null | Up to 200 characters. |
active | boolean |
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)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
urlrequired | string | |
eventsrequired | enum[] | |
collectionIdrequired | uuid or null | |
descriptionrequired | string or null | |
activerequired | boolean | |
disabledReasonrequired | string or null | |
consecutiveFailuresrequired | integer | -9007199254740991–9007199254740991. |
lastDeliveryAtrequired | string or null | |
createdAtrequired | string | |
updatedAtrequired | string |
delete /v1/webhooks/{id}
Delete a webhook (Zapier unsubscribes here).
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In 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)
| Name | Type | Description |
|---|---|---|
messagerequired | string |
get /v1/webhooks/{id}/deliveries
Recent deliveries, newest first (kept 30 days).
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
cursor | uuid | |
limit | integer | Default 25. 1–100. |
idrequired | uuid | In the path. |
Example
curl 'https://api.bkmark.it/v1/webhooks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/deliveries' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (2)
| Name | Type | Description |
|---|---|---|
datarequired | object[] | |
idrequired | uuid | |
eventrequired | string | |
statusrequired | enum | One of pending, success, failed. |
attemptsrequired | integer | -9007199254740991–9007199254740991. |
responseStatusrequired | integer or null | -9007199254740991–9007199254740991. |
errorrequired | string or null | |
durationMsrequired | integer or null | -9007199254740991–9007199254740991. |
deliveredAtrequired | string or null | |
createdAtrequired | string | |
payloadrequired | object | |
nextCursorrequired | string 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
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In 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)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
eventrequired | string | |
statusrequired | enum | One of pending, success, failed. |
attemptsrequired | integer | -9007199254740991–9007199254740991. |
responseStatusrequired | integer or null | -9007199254740991–9007199254740991. |
errorrequired | string or null | |
durationMsrequired | integer or null | -9007199254740991–9007199254740991. |
deliveredAtrequired | string or null | |
createdAtrequired | string | |
payloadrequired | object |