From 0193d2bfb9e3f8e8c8ef3456e38efcd9819b91b1 Mon Sep 17 00:00:00 2001 From: "Qays H. Poonawala" Date: Thu, 23 Jul 2026 09:59:03 -0700 Subject: [PATCH 1/3] docs: document webhook management API --- server/SUMMARY.md | 1 + .../webhook-management-api.md | 130 ++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 server/developer-guides/webhook-management-api.md diff --git a/server/SUMMARY.md b/server/SUMMARY.md index 2dabdfd..0938b5a 100644 --- a/server/SUMMARY.md +++ b/server/SUMMARY.md @@ -66,5 +66,6 @@ * [Developer Guides - Overview](developer-guides/developer-guides-overview.md) * [Build Yourself / Contribution Guide](developer-guides/build-yourself-contribution-guide.md) * [REST API & Webhooks](developer-guides/rest-api-and-webhooks.md) +* [Webhook Management API](developer-guides/webhook-management-api.md) * [Simple Web Server for Webhooks](developer-guides/simple-web-server-for-webhooks/README.md) * [Python Web Server Example](developer-guides/simple-web-server-for-webhooks/python-web-server.md) diff --git a/server/developer-guides/webhook-management-api.md b/server/developer-guides/webhook-management-api.md new file mode 100644 index 0000000..a8877c0 --- /dev/null +++ b/server/developer-guides/webhook-management-api.md @@ -0,0 +1,130 @@ +--- +description: Create, list, and delete BlueBubbles webhooks through the REST API +--- + +# Webhook Management API + +The webhook management endpoints let you configure a server without using the BlueBubbles desktop interface. They are useful for automated and declarative installations. + +All examples below use these shell variables: + +```bash +export BLUEBUBBLES_URL="https://your-server.example.com" +read -s BLUEBUBBLES_PASSWORD +export BLUEBUBBLES_PASSWORD +``` + +Enter the BlueBubbles server password when prompted by `read`. + +{% hint style="warning" %} +Webhook management requests authenticate through a query parameter. Use HTTPS, avoid placing the password directly in scripts or shell history, and take care not to copy authenticated request URLs into logs. +{% endhint %} + +The examples use `password`, but the `guid` and `token` query parameter aliases also work. Every endpoint is under `/api/v1/webhook`. + +## List webhooks + +Use `GET /api/v1/webhook` to retrieve all configured webhooks: + +```bash +curl --silent --show-error \ + --url-query "password=$BLUEBUBBLES_PASSWORD" \ + "$BLUEBUBBLES_URL/api/v1/webhook" +``` + +A successful response contains an array of webhook records: + +```json +{ + "status": 200, + "message": "Successfully fetched webhooks!", + "data": [ + { + "id": 1, + "url": "https://automation.example.com/bluebubbles", + "events": [ + "new-message", + "updated-message" + ], + "created": "2026-01-01T00:00:00.000Z" + } + ] +} +``` + +To retrieve one webhook, include its numeric `id`: + +```bash +curl --silent --show-error \ + --url-query "password=$BLUEBUBBLES_PASSWORD" \ + --url-query "id=1" \ + "$BLUEBUBBLES_URL/api/v1/webhook" +``` + +## Create a webhook + +Use `POST /api/v1/webhook` with a JSON body containing: + +* `url`: The HTTP or HTTPS endpoint that will receive webhook requests. HTTPS is strongly recommended. +* `events`: An array of webhook event keys. See [REST API & Webhooks](rest-api-and-webhooks.md#webhooks) for the supported events. Use `*` to subscribe to every event. + +```bash +curl --silent --show-error \ + --request POST \ + --url-query "password=$BLUEBUBBLES_PASSWORD" \ + --header "Content-Type: application/json" \ + --data '{ + "url": "https://automation.example.com/bluebubbles", + "events": ["new-message", "updated-message"] + }' \ + "$BLUEBUBBLES_URL/api/v1/webhook" +``` + +The response includes the webhook's generated `id`: + +```json +{ + "status": 200, + "message": "Successfully created webhook!", + "data": { + "id": 1, + "url": "https://automation.example.com/bluebubbles", + "events": [ + "new-message", + "updated-message" + ], + "created": "2026-01-01T00:00:00.000Z" + } +} +``` + +Webhook URLs are unique. Posting a URL that is already registered returns the existing webhook without changing its event subscriptions. To replace its subscriptions through the REST API, delete the existing webhook and then create it again. + +## Delete a webhook + +Use `DELETE /api/v1/webhook/:id`, replacing `:id` with the numeric webhook ID: + +```bash +curl --silent --show-error \ + --request DELETE \ + --url-query "password=$BLUEBUBBLES_PASSWORD" \ + "$BLUEBUBBLES_URL/api/v1/webhook/1" +``` + +A successful deletion returns: + +```json +{ + "status": 200, + "message": "Successfully deleted webhook!" +} +``` + +Deleting an ID that does not exist returns `404`. + +## Troubleshooting + +* `400 Bad Request`: Check that `url` starts with `http` and every item in `events` is a supported string event key. +* `401 Unauthorized`: Check that an authentication query parameter is present and matches the server password. +* `404 Not Found`: The webhook ID in a delete request does not exist. + From 39197da09a369f8c8f5b229b74b12f10c98351cd Mon Sep 17 00:00:00 2001 From: "Qays H. Poonawala" Date: Thu, 23 Jul 2026 15:01:32 -0700 Subject: [PATCH 2/3] docs: fix webhook page formatting --- server/developer-guides/webhook-management-api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/server/developer-guides/webhook-management-api.md b/server/developer-guides/webhook-management-api.md index a8877c0..9526ae0 100644 --- a/server/developer-guides/webhook-management-api.md +++ b/server/developer-guides/webhook-management-api.md @@ -127,4 +127,3 @@ Deleting an ID that does not exist returns `404`. * `400 Bad Request`: Check that `url` starts with `http` and every item in `events` is a supported string event key. * `401 Unauthorized`: Check that an authentication query parameter is present and matches the server password. * `404 Not Found`: The webhook ID in a delete request does not exist. - From 6ffc4e1dda100f95041c5bdfa53a418e31615250 Mon Sep 17 00:00:00 2001 From: "Qays H. Poonawala" Date: Sat, 25 Jul 2026 14:38:50 -0700 Subject: [PATCH 3/3] docs: support older curl in webhook examples --- .../webhook-management-api.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/server/developer-guides/webhook-management-api.md b/server/developer-guides/webhook-management-api.md index 9526ae0..ff4c23a 100644 --- a/server/developer-guides/webhook-management-api.md +++ b/server/developer-guides/webhook-management-api.md @@ -12,15 +12,21 @@ All examples below use these shell variables: export BLUEBUBBLES_URL="https://your-server.example.com" read -s BLUEBUBBLES_PASSWORD export BLUEBUBBLES_PASSWORD +BLUEBUBBLES_PASSWORD_QUERY="$( + printf '%s' "$BLUEBUBBLES_PASSWORD" | + od -An -tx1 | + tr -d ' \n' | + sed 's/../%&/g' +)" ``` -Enter the BlueBubbles server password when prompted by `read`. +Enter the BlueBubbles server password when prompted by `read`. The final command percent-encodes every password byte for safe use in a query string using utilities included with macOS. {% hint style="warning" %} Webhook management requests authenticate through a query parameter. Use HTTPS, avoid placing the password directly in scripts or shell history, and take care not to copy authenticated request URLs into logs. {% endhint %} -The examples use `password`, but the `guid` and `token` query parameter aliases also work. Every endpoint is under `/api/v1/webhook`. +The examples use `password`, but the `guid` and `token` query parameter aliases also work. Every endpoint is under `/api/v1/webhook`. The pre-encoded query value avoids curl's newer `--url-query` option, so these commands also work with older curl versions bundled with supported macOS releases. ## List webhooks @@ -28,8 +34,7 @@ Use `GET /api/v1/webhook` to retrieve all configured webhooks: ```bash curl --silent --show-error \ - --url-query "password=$BLUEBUBBLES_PASSWORD" \ - "$BLUEBUBBLES_URL/api/v1/webhook" + "$BLUEBUBBLES_URL/api/v1/webhook?password=$BLUEBUBBLES_PASSWORD_QUERY" ``` A successful response contains an array of webhook records: @@ -56,9 +61,7 @@ To retrieve one webhook, include its numeric `id`: ```bash curl --silent --show-error \ - --url-query "password=$BLUEBUBBLES_PASSWORD" \ - --url-query "id=1" \ - "$BLUEBUBBLES_URL/api/v1/webhook" + "$BLUEBUBBLES_URL/api/v1/webhook?password=$BLUEBUBBLES_PASSWORD_QUERY&id=1" ``` ## Create a webhook @@ -71,13 +74,12 @@ Use `POST /api/v1/webhook` with a JSON body containing: ```bash curl --silent --show-error \ --request POST \ - --url-query "password=$BLUEBUBBLES_PASSWORD" \ --header "Content-Type: application/json" \ --data '{ "url": "https://automation.example.com/bluebubbles", "events": ["new-message", "updated-message"] }' \ - "$BLUEBUBBLES_URL/api/v1/webhook" + "$BLUEBUBBLES_URL/api/v1/webhook?password=$BLUEBUBBLES_PASSWORD_QUERY" ``` The response includes the webhook's generated `id`: @@ -107,8 +109,7 @@ Use `DELETE /api/v1/webhook/:id`, replacing `:id` with the numeric webhook ID: ```bash curl --silent --show-error \ --request DELETE \ - --url-query "password=$BLUEBUBBLES_PASSWORD" \ - "$BLUEBUBBLES_URL/api/v1/webhook/1" + "$BLUEBUBBLES_URL/api/v1/webhook/1?password=$BLUEBUBBLES_PASSWORD_QUERY" ``` A successful deletion returns: