Add Watchgoose monitoring hook #1335

New issue

Closed

opened 2026-07-18 20:58:18 +00:00 by witten · 4 comments

witten commented 2026-07-18 20:58:18 +00:00

Owner

Copy link

What I'd like to do and why

Watchgoose is a Europe-hosted and owned service for monitoring backups, cron jobs, Kubernetes jobs, scripts, etc. (They contribute a portion of profits to open source projects and provide free monitoring for them as well.)

This ticket is for adding a native Watchgoose monitoring hook to borgmatic. Reportedly, the existing Healthchecks hook actually works with Watchgoose when configuring a Watchgoose ping URL instead of a Healthchecks one. That likely means that the Healthchecks hook can be forked to serve as a basis for any Watchgoose hook.

Open questions that should be answered before this work can begin:

• Does Watchgoose have a log state like Healthchecks does? Do sent logs get surfaced somewhere in the Watchgoose UI?
• Does Watchgoose support auto-provisioning like Healthchecks does, e.g. ?create=1 on certain ping URLs to create a new monitor from the command-line?
• Does Watchgoose have the same ping URL uuid format as Healthchecks does, or does the format differ? If so, what is it?
• Is there a ping body size limit for Watchgoose? What is it? (borgmatic will truncate logs to fit in this limit if needed.)
• Anything else we should know that differs from Healthchecks semantics?
• Could I get a Watchgoose test/dev account for manually testing this implementation? (Please don't provide credentials here though.) Maybe I should just sign up for your free tier? I think my big question is if the free tier does log entries at all.

As for implementation to dos:

• Get the above questions resolved.
• Fork the Healthchecks hook and make appropriate modifications.
• Copy the schema, adding a new watchgoose: option. Modify as appropriate.
• Manually test. Some tests that have been done already with the Healthchecks hook:
  • Successful backup: /start, then the base success ping; recorded as a 2-second run and up
  • Invalid repository: /start, then /fail; down immediately, alert delivered
• Add automated tests.
• Update documentation.

Other notes / implementation ideas

No response

### What I'd like to do and why [Watchgoose](https://watchgoose.com/) is a Europe-hosted and owned service for monitoring backups, cron jobs, Kubernetes jobs, scripts, etc. (They [contribute a portion of profits](https://watchgoose.com/open-source/) to open source projects and provide free monitoring for them as well.) This ticket is for adding a native Watchgoose monitoring hook to borgmatic. Reportedly, the existing Healthchecks hook actually works with Watchgoose when configuring a Watchgoose ping URL instead of a Healthchecks one. That likely means that the Healthchecks hook can be forked to serve as a basis for any Watchgoose hook. Open questions that should be answered before this work can begin: * [x] Does Watchgoose have a `log` state like Healthchecks does? Do sent logs get surfaced somewhere in the Watchgoose UI? * [x] Does Watchgoose support auto-provisioning like Healthchecks does, e.g. `?create=1` on certain ping URLs to create a new monitor from the command-line? * [x] Does Watchgoose have the same ping URL uuid format as Healthchecks does, or does the format differ? If so, what is it? * [x] Is there a ping body size limit for Watchgoose? What is it? (borgmatic will truncate logs to fit in this limit if needed.) * [x] Anything else we should know that differs from Healthchecks semantics? * [x] Could I get a Watchgoose test/dev account for manually testing this implementation? (Please don't provide credentials here though.) Maybe I should just sign up for your free tier? I think my big question is if the free tier does log entries at all. As for implementation to dos: * [x] Get the above questions resolved. * [x] Fork the Healthchecks hook and make appropriate modifications. * [x] Copy the schema, adding a new `watchgoose:` option. Modify as appropriate. * [x] Manually test. Some tests that have been done already with the Healthchecks hook: * [x] Successful backup: /start, then the base success ping; recorded as a 2-second run and up * [x] Invalid repository: /start, then /fail; down immediately, alert delivered * [x] Add automated tests. * [x] Update documentation. ### Other notes / implementation ideas _No response_

witten added the

new feature area

label 2026-07-18 20:58:18 +00:00

watchgoose commented 2026-08-01 11:09:37 +00:00

Copy link

Hi Dan,

Thanks for taking care of this. Answers in the order:

1. Yes. Watchgoose supports the /log state. A request to https://watchgoose.com/ping/<uuid>/log records the provided body as a log event. The event and body are visible in the check event history and ping details UI. A log event is state neutral, it does not mark the check up or down, reset its expected schedule or trigger an alert.

2. Yes. Watchgoose supports auto provisioning using the ping-key/slug URL form: https://watchgoose.com/ping/<ping-key>/<lowercase-slug>?create=1. The create=1 option applies only to the ping key/slug form, not UUID URLs.

An existing check returns 200 OK, a newly created check returns 201 Created. A missing check without create=1 returns 404 Not Found. If the account has reached its check limit, Watchgoose returns 403 with the plain text body check limit reached. An ambiguous duplicate slug returns 409 with ambiguous slug.

3. The normal Watchgoose ping URL uses the same standard UUID format: https://watchgoose.com/ping/<uuid>.
   The lifecycle suffixes are also the same:

• https://watchgoose.com/ping/<uuid>/start
• https://watchgoose.com/ping/<uuid>/fail
• https://watchgoose.com/ping/<uuid>/log

Exit-status suffixes from /0 through /255 are supported as well. Status 0 means success, while a non zero status means failure. The optional rid=<uuid> query parameter is supported for associating lifecycle events with the same run.

4. The current ping body limit is 10,000 bytes. Watchgoose truncates larger request bodies to that limit and includes this response header: Ping-Body-Limit: 10000. Borgmatic can safely truncate logs to 10,000 bytes before sending them.

5. The ping protocol is compatible with modern Healthchecks semantics. Watchgoose accepts GET, POST, HEAD, and other HTTP methods. Successful normal pings return plain-text OK with HTTP 200; newly auto-provisioned checks return plain text Created with HTTP 201.

The main deliberate difference is auto provisioning at the plan limit: Watchgoose rejects creation immediately with HTTP 403 rather than allowing Healthchecks’ additional check-count headroom. Plan limits and event-retention counts also differ.

6. Yes, signing up for the free tier is the right approach for development and manual testing: https://watchgoose.com/accounts/signup/

The free tier includes 10 checks and retains the newest 200 events per check. /log events and their bodies are recorded and displayed on the free tier in the same way as on paid plans so it should be sufficient for implementing and testing the hook.

Let me know if you'd have any more questions or would need any help around this implementation.

Kind regards,
Bartek Rutkowski

Hi Dan, Thanks for taking care of this. Answers in the order: 1) Yes. Watchgoose supports the `/log` state. A request to `https://watchgoose.com/ping/<uuid>/log` records the provided body as a log event. The event and body are visible in the check event history and ping details UI. A log event is state neutral, it does not mark the check up or down, reset its expected schedule or trigger an alert. 2) Yes. Watchgoose supports auto provisioning using the ping-key/slug URL form: `https://watchgoose.com/ping/<ping-key>/<lowercase-slug>?create=1`. The `create=1` option applies only to the ping key/slug form, not UUID URLs. An existing check returns `200 OK`, a newly created check returns `201 Created`. A missing check without `create=1` returns `404 Not Found`. If the account has reached its check limit, Watchgoose returns `403` with the plain text body `check limit reached`. An ambiguous duplicate slug returns `409` with `ambiguous slug`. 3) The normal Watchgoose ping URL uses the same standard UUID format: `https://watchgoose.com/ping/<uuid>`. The lifecycle suffixes are also the same: - `https://watchgoose.com/ping/<uuid>/start` - `https://watchgoose.com/ping/<uuid>/fail` - `https://watchgoose.com/ping/<uuid>/log` Exit-status suffixes from `/0` through `/255` are supported as well. Status `0` means success, while a non zero status means failure. The optional `rid=<uuid>` query parameter is supported for associating lifecycle events with the same run. 4) The current ping body limit is 10,000 bytes. Watchgoose truncates larger request bodies to that limit and includes this response header: `Ping-Body-Limit: 10000`. Borgmatic can safely truncate logs to 10,000 bytes before sending them. 5) The ping protocol is compatible with modern Healthchecks semantics. Watchgoose accepts GET, POST, HEAD, and other HTTP methods. Successful normal pings return plain-text `OK` with HTTP 200; newly auto-provisioned checks return plain text `Created` with HTTP 201. The main deliberate difference is auto provisioning at the plan limit: Watchgoose rejects creation immediately with HTTP 403 rather than allowing Healthchecks’ additional check-count headroom. Plan limits and event-retention counts also differ. 6) Yes, signing up for the free tier is the right approach for development and manual testing: https://watchgoose.com/accounts/signup/ The free tier includes 10 checks and retains the newest 200 events per check. `/log` events and their bodies are recorded and displayed on the free tier in the same way as on paid plans so it should be sufficient for implementing and testing the hook. Let me know if you'd have any more questions or would need any help around this implementation. Kind regards, Bartek Rutkowski

witten commented 2026-08-08 19:28:01 +00:00

Author

Owner

Copy link

Thanks, this is all very helpful! I think for this initial version, I'll focus on parity with the existing Healthchecks feature set. And then we can always discuss additional features (e.g. rid=, etc.) on future tickets.

Thanks, this is all very helpful! I think for this initial version, I'll focus on parity with the existing Healthchecks feature set. And then we can always discuss additional features (e.g. `rid=`, etc.) on future tickets.

witten referenced this issue from a commit 2026-08-08 20:33:48 +00:00

Add a Watchgoose monitoring hook (#1335).

witten commented 2026-08-08 20:34:09 +00:00

Author

Owner

Copy link

This is implemented in main and will be part of the next release. Thanks again!

This is implemented in main and will be part of the next release. Thanks again!

witten closed this issue 2026-08-08 20:34:09 +00:00

witten referenced this issue from a commit 2026-08-08 21:38:33 +00:00

Tweak Watchgoose logo size (#1335).

witten commented 2026-08-14 20:16:35 +00:00

Author

Owner

Copy link

Released in borgmatic 2.1.7!

Released in borgmatic 2.1.7!

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

parallel-borgmatic

command-hook-steps

2.1.7

2.1.6

2.1.5

2.1.4

2.1.3

2.1.2

2.1.1

2.1.0

2.0.13

2.0.12

2.0.11

2.0.10

2.0.9

2.0.8

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0.1

2.0.0

1.9.14

1.9.13

1.9.12

1.9.11

1.9.10

1.9.9

1.9.8

1.9.7

1.9.6

1.9.5

1.9.4

1.9.3

1.9.2

1.9.1

1.9.0

1.8.14

1.8.13

1.8.12

1.8.11

1.8.10

1.8.9

1.8.8

1.8.7

1.8.6

1.8.5

1.8.4

1.8.3

1.8.2

1.8.1

1.8.0

1.7.15

1.7.14

1.7.13

1.7.12

1.7.11

1.7.10

1.7.9

1.7.8

1.7.7

1.7.6

1.7.5

1.7.4

1.7.3

1.7.2

1.7.1

1.7.0

1.6.6

1.6.5

1.6.4

1.6.3

1.6.2

1.6.1

1.6.0

1.5.24

1.5.23

1.5.22

1.5.21

1.5.20

1.5.19

1.5.18

1.5.17

1.5.16

1.5.15

1.5.14

1.5.13

1.5.12

1.5.11

1.5.10

1.5.9

1.5.8

1.5.7

1.5.7.dev0

1.5.6

1.5.5

1.5.4

1.5.3

1.5.2

1.5.1

1.5.0

1.4.22

1.4.21

1.4.20

1.4.19

1.4.18

1.4.17

1.4.16

1.4.15

1.4.14

1.4.13

1.4.12

1.4.11

1.4.10

1.4.9

1.4.8

1.4.7

1.4.6

1.4.5

1.4.4

1.4.3

1.4.2

1.4.1

1.4.0

1.3.26

1.3.25

1.3.24

1.3.23

1.3.22

1.3.21

1.3.20

1.3.19

1.3.18

1.3.17

1.3.16

1.3.15

1.3.14

1.3.13

1.3.12

1.3.11

1.3.10

1.3.9

1.3.8

1.3.7

1.3.6

1.3.5

1.3.4

1.3.3

1.3.2

1.3.1

1.3.0

1.2.18

1.2.17

1.2.16

1.2.15

1.2.14

1.2.13

1.2.12

1.2.11

1.2.10

1.2.9

1.2.8

1.2.7

1.2.6

1.2.5

1.2.4

1.2.3

1.2.2

1.2.1

1.2.0

1.1.15

1.1.14

1.1.13

1.1.12

1.1.11

1.1.10

1.1.9

1.1.7

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.1.1

1.1.0

1.0.3

1.0.2

1.0.1

1.0.0

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

Labels

Clear labels   

blocked

  

breaking

  

bug

  

data loss

  

design finalized

  

good first issue

  

new feature area

  

question / support

  

security

  

waiting for response

No labels

blocked

breaking

bug

data loss

design finalized

good first issue

new feature area

question / support

security

waiting for response

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

borgmatic-collective/borgmatic#1335

No description provided.