[Blog](https://sparetext.dev/blog)

# Uptime Kuma SMS alerts from your own phone, with one webhook

Uptime Kuma's webhook can text you when a site goes down, from your own number, with no SMS account. Here's the Custom Body that survives quotes in the error message, and why its example template breaks.

Sparetext

6 min read · Nov 18, 2026

Uptime Kuma is great at noticing your site is down. Getting that news to you at 3am is the harder part: an email waits until morning, and most of the SMS options it ships with want an account with an SMS company first.

Short answer: yes, Uptime Kuma can text you from your own phone. Its Webhook notification can call the Sparetext API, and Sparetext sends the text from the Android phone you already own, on your number. You need one Custom Body and one header. The catch is in the body, and it's the template Uptime Kuma itself shows as the example.

What we tested, plainly: we didn't run Uptime Kuma. We read the source of Uptime Kuma 2.5.12 (released 17 November 2026) to see exactly what its webhook sends, then sent that same request to a test copy of Sparetext with a simulated phone on 18 November. Every result below comes from that run.

## What you need

- A Sparetext account. Free is 1 phone and 300 texts a month, which is a lot of outages.
- An Android phone with the Sparetext app, paired in the dashboard.
- An API key from the API keys page. Make one just for Uptime Kuma, with a daily limit, so a flapping monitor can't spend your month.
- Uptime Kuma, any recent version with the Webhook notification and Custom Body (2.5.12 is what we read).

## Set up the webhook

Open a monitor's edit page and click Set Up Notification (or add it under Settings, Notifications, so every monitor can use it). Then fill it in like this:

1. Notification Type: Webhook.
2. Friendly Name: whatever you like, say "Text me".
3. Post URL: `https://sparetext.dev/api/v1/messages`
4. HTTP Method: POST.
5. Request Body: Custom Body, with the template in the next section.
6. Additional Headers: tick it and paste the JSON below, with your key in it.

Additional Headers

```json
{
  "x-api-key": "spt_live_...",
  "Content-Type": "application/json"
}
```

`Authorization: Bearer spt_live_...` works too, if you'd rather match the example Uptime Kuma puts in that box. Why the Content-Type line? Uptime Kuma sends a Custom Body as plain text through axios 0.32, and axios labels plain text as `application/x-www-form-urlencoded` unless you say otherwise. Our API reads the JSON either way (we tried it without the header and it went through), but other APIs won't, so it's a good habit.

## The Custom Body that doesn't break

Custom Body

```json
{% capture text %}{% if heartbeatJSON %}{% if heartbeatJSON.status == 1 %}UP{% else %}DOWN{% endif %}: {{ name }}. {{ heartbeatJSON.msg }}{% else %}Test from Uptime Kuma{% endif %}{% endcapture %}
{"to": "+12025550187", "text": {{ text | truncate: 150 | json }}}
```

Put your own number in `to`, with its country code. Keep the first line on one line: everything inside `capture` ends up in the text, line breaks included.

Here's what each part does. Uptime Kuma renders the body with Liquid templates and hands it `name` (the monitor's name), `heartbeatJSON` (the check that changed, with `status` 1 for up and 0 for down, and `msg`, the reason) and `msg` (its own one-line summary). When you press Test, there's no heartbeat at all, so the `if` gives you a test line instead of a half-empty text. `truncate: 150` keeps a long error inside one SMS. And `json` is the important one, which brings us to the bug.

## Why the example template breaks

The placeholder in Uptime Kuma's Custom Body box puts the message inside quotes, like `"Body": "{{ msg }}"`. It looks fine, and it works for most messages. Then one day the message has a quote in it, and the JSON breaks.

That day comes sooner than you'd think. A keyword monitor that doesn't find its word puts a piece of the page into the message. If your health check returns JSON, the message looks like this:

text

```json
[Shop API] [🔴 Down] 200 - OK, but keyword is not in [{"status":"maintenance","eta":"20 min"}]
```

We sent exactly that through the quoted template, and the API answered `400`: "The body must be a JSON object." No text. Your site is down and the alert about it failed too, which is kind of the worst way to find a bug.

The `json` filter fixes it. It turns the text into a proper JSON string, quotes, brackets and all, and adds the outer quotes itself. That's why there are no quotes around `{{ text | truncate: 150 | json }}` in our template. With the same keyword message, ours went through, and the simulated phone got the whole thing, starting `DOWN: Shop API.` and ending with `{"status":"maintenance","eta":"20 min"}` in brackets, every quote where it should be.

## Why it says DOWN and not the red circle

You could skip the `capture` and just send `{{ msg | json }}`. It's valid JSON and we sent it fine. But Uptime Kuma's summary starts with an emoji, `🔴 Down` or `✅ Up`, and one emoji switches the whole SMS to UCS-2 encoding: 70 characters per text instead of 160, or 67 per part once it's split. [Here's why one emoji can double your SMS](https://sparetext.dev/blog/why-one-emoji-can-double-your-sms).

We counted the keyword alert above. Uptime Kuma's version with the emoji is 94 characters, so it goes as 2 SMS. Ours, with DOWN in plain letters, is 89 characters (93 once you count brackets and braces, which take two places each in GSM-7) and fits in 1. On a phone plan with unlimited texts that doesn't matter much. On a plan that counts them, or when the reason is long, it's every alert costing double.

## What we saw in the test

- The quoted `"{{ msg }}"` template with the keyword message: `400 bad_request`, nothing sent.
- Our template, DOWN with the same message: `202`, then delivered.
- Our template, UP: `UP: Shop API.` and the reason, delivered.
- The Test button case (no heartbeat): `Test from Uptime Kuma`, delivered.
- No Content-Type header, as axios would send it: `202`, delivered.
- `Authorization: Bearer` instead of `x-api-key`: `202`, delivered.

The simulated phone reports "delivered" within a second or two. A real phone on a real network takes longer, and it depends on your carrier, so don't read our timings as a promise.

## How many texts you'll get

Uptime Kuma sends a notification when a monitor goes down and again when it comes back up, so one outage is two texts. It doesn't repeat while the site stays down unless you turn on "Resend Notification if Down X times consecutively" in the monitor's settings; it's 0, off, by default. A monitor that flaps up and down every few minutes will text you every time, which is what the daily limit on your key is for. If a monitor flaps a lot, raise its retries in Uptime Kuma so it's sure before it calls you.

## What this can't do

This is the easy case for a phone: texts to yourself and your team, people who want them. Up to a handful of people, add a second notification with a different `to`. It isn't the tool for texting a big list of customers about an outage; carriers filter business texts sent by software, even from a personal number ([the 10DLC post](https://sparetext.dev/blog/send-sms-without-10dlc) explains). Only Android phones get carrier delivery reports; an iPhone can do this through Sparetext for Mac ([the iPhone guide](https://sparetext.dev/iphone-sms-gateway)), and "sent" is as far as it reports.

And the obvious one: if the outage is your phone's network, or the phone's battery is dead, the text waits. For alerts you can't miss, keep a second channel too. Uptime Kuma also has built-in SMS notification types for services like Twilio, ClickSend and 46elks, which make sense if you already pay one of them.

If your checks are a cron job and not Uptime Kuma, the [curl and bash post](https://sparetext.dev/blog/send-sms-from-bash-with-curl) has a disk alert that texts you once an hour while it's broken. The [Android SMS gateway guide](https://sparetext.dev/android-sms-gateway) covers the phone side.

## Try it on one monitor

Make a key with a daily limit on the API keys page, paste the template with your number into one monitor's webhook, and press Test. When "Test from Uptime Kuma" lands on your phone, turn on Default enabled and Apply on all existing monitors, and go back to sleep.

uptime kuma sms alerts monitoring webhook self-hosted tutorial

Try it with the phone you have

Free for 1 phone and 300 texts a month. Pair it in about two minutes.

[Start free](https://sparetext.dev/signup)

## Responses

[Sign in](https://sparetext.dev/login?next=%2Fblog%2Fuptime-kuma-sms-alerts%23responses) or [create an account](https://sparetext.dev/signup?next=%2Fblog%2Fuptime-kuma-sms-alerts%23responses) to respond.

## More from the blog

- **[Your first text from code in five minutes, timed against Twilio's steps](https://sparetext.dev/blog/first-text-from-code-in-five-minutes)**
   5 min read
- **[We handed our dashboard to two AI agents: this week in Sparetext](https://sparetext.dev/blog/we-handed-our-dashboard-to-two-ai-agents)**
   5 min read
- **[Is there a free SMS API with no credit card? Six of them, checked](https://sparetext.dev/blog/free-sms-api-no-credit-card)**
   5 min read

---

This is the Markdown copy of https://sparetext.dev/blog/uptime-kuma-sms-alerts for AI agents. Every public page has one: add .md to its address (the home page is https://sparetext.dev/index.md). Sparetext for agents in one file: https://sparetext.dev/llms.txt
