Monitor Dew from your monitoring tool

Your monitoring tool can warn you when Dew needs attention: a certificate or the license about to expire, storage running out, email failing, or the license running out of users. Dew already raises these as alerts under the bell in the web app; the monitoring tool reads the same alerts over the API, so you hear about them where you watch everything else.

Before you start, create a service account and token for the monitoring tool:

Under Permissions, select only Server status in the Monitoring group.
Under Domains, select any one. These checks don’t use it.
Choose Never expires for the token, or set a date and replace the token before then. Dew alerts admins a week before a token expires.

The token starts with dewsa_. Copy all of it.

What to check

Check	Request	Warn when
Dew answers	`GET https://files.example.com/`	Not `200`
Open alerts	`GET /api/admin/notifications/count`	`data.severity` is `warn` or `error`
License	`GET /api/admin/license`	`data.valid` is `false`
Users	`GET /api/admin/license`	`data.effective_users` reaches a number you choose, below `data.max_users`

Every request except the first sends the header Authorization: Bearer dewsa_<token>, and every path starts with your Dew address, such as https://files.example.com/api/admin/license. Checking every 5 minutes is plenty.

Open alerts covers most of what goes wrong: certificates expiring or failing to renew, the license expiring, storage running low or unreachable, email delivery failing, and API tokens expiring. GET /api/admin/notifications lists them, each with a title, a message and a severity: warn or error for a problem, info for a notice such as features turned back on after a license change. data.count counts every open alert, notices included; data.severity is the most serious one, or empty when only notices are open. An alert stays open until an admin dismisses it under the bell in Dew, so after fixing the cause, dismiss the alert there.

Users: effective_users counts active users plus pending invitations, which is what the license limits. Service accounts don’t count as users on the license. max_users is the number of users the license includes.

Use an HTTP check with a JSON condition

Most monitoring tools can call a URL and check a value in the JSON it returns, such as Uptime Kuma’s HTTP(s) - Json Query monitor or Zabbix’s HTTP agent item. Make one check per row of the table:

URL: the request, such as https://files.example.com/api/admin/notifications/count
Header: Authorization: Bearer dewsa_<token>
Value: the field. In Uptime Kuma, the JSON query data.severity = "". In Zabbix, a text item with a JSONPath preprocessing step $.data.severity.
Condition: when to warn, from the table. In Uptime Kuma, the expected value true. In Zabbix, a trigger on the item, such as length(last(/Dew/dew.alerts))>0.

Or use a check script

For Nagios, Icinga, Checkmk, or Zabbix as an external check, this script makes all four checks and answers in the standard plugin way: one line of text, and exit code 0 (OK), 1 (warning), 2 (critical) or 3 (unknown, when it couldn’t check). It needs curl 7.76 or later and jq. Save it as check_dew.sh, make it executable with chmod +x check_dew.sh, and change DEW to your Dew address.

#!/bin/sh
DEW="https://files.example.com"
USERS_WARN="${USERS_WARN:-90}"  # warn when this percentage of the license's users is in use
[ -n "$DEW_TOKEN" ] || { echo "UNKNOWN - Set DEW_TOKEN to the service account token"; exit 3; }

get() { curl -sS --fail-with-body --max-time 20 -H "Authorization: Bearer $DEW_TOKEN" "$DEW$1"; }
unknown() { echo "UNKNOWN - $1"; exit 3; }

curl -sS --fail -o /dev/null --max-time 20 "$DEW/" || { echo "CRITICAL - Dew doesn't answer"; exit 2; }

license=$(get /api/admin/license) || unknown "$license"
valid=$(printf '%s\n' "$license" | jq -r '.data.valid')
case "$valid" in true|false) ;; *) unknown "Unexpected answer: $license" ;; esac
if [ "$valid" = false ]; then
  echo "CRITICAL - License not valid: $(printf '%s\n' "$license" | jq -r '.data.validation_error // ""')"; exit 2
fi
used=$(printf '%s\n' "$license" | jq -er '.data.effective_users') || unknown "Unexpected answer: $license"
max=$(printf '%s\n' "$license" | jq -er '.data.max_users') || unknown "Unexpected answer: $license"
users="$used of $max users in use"

alerts=$(get /api/admin/notifications) || unknown "$alerts"
titles=$(printf '%s\n' "$alerts" | jq -er '[.data[] | select(.severity != "info") | .title] | join("; ")') || unknown "Unexpected answer: $alerts"
errors=$(printf '%s\n' "$alerts" | jq -er '[.data[] | select(.severity == "error")] | length') || unknown "Unexpected answer: $alerts"

if [ "$errors" -gt 0 ]; then echo "CRITICAL - $titles. $users"; exit 2; fi
if [ -n "$titles" ]; then echo "WARNING - $titles. $users"; exit 1; fi
if [ "$max" -gt 0 ] && [ $((used * 100 / max)) -ge "$USERS_WARN" ]; then echo "WARNING - $users"; exit 1; fi
echo "OK - $users, no open alerts"

Give the script the token through the monitoring tool’s own secret store or environment, as DEW_TOKEN, rather than writing it into the script. Set USERS_WARN the same way to change the percentage.

Check it worked

Run the check once by hand with DEW_TOKEN="dewsa_<token>" ./check_dew.sh: it prints OK with the users in use. To see a warning, run it again with USERS_WARN=1 in front.

If something doesn’t work

What you see	What to do
`403` with “This API token doesn’t have permission for this action.”	Select Server status under Monitoring on the service account.
`403` on every call, with the right permission	The monitoring server’s IP address isn’t on the Admin pages IP allowlist, if you use one. Add it in Settings → General settings → Advanced.
`401` with “This API token has expired.”	Regenerate the token on the service account’s page in System → Integrations.
The warning stays after you fixed the problem	Dismiss the alert under the bell in Dew.

Every endpoint used here is in the Monitoring API reference.