Shell script push notification: three shapes and the errors you will hit
Inline, shared function or wrapper command, plus the six JSON error codes worth branching on.
·3 min read
A shell script push notification is the smallest possible automation: no daemon, no queue, no library, just an HTTP request at the moment a script decides something is wrong. For anyone running cron jobs, rsync pairs or deploy hooks, it is the difference between noticing a failure and hearing about it.
The minimal version
curl https://ayeping.com/@you \
-H "Authorization: Bearer $AYEPING_TOKEN" \
-d "rsync failed on $(hostname)"
The body is the title, capped at 100 characters on a single line. The credential is a bearer token created in the app on the Tokens page, as described in the AyePing documentation. A successful request returns 202 with a ping id.
That is the entire integration. Everything below is about making it survive real use.
Three shapes for the same call
| Shape | When to use it | Trade-off |
|---|---|---|
| Inline curl | One script, one failure path | Duplicated if you have five scripts |
A shared function in lib.sh |
Several scripts on one host | Needs a sourced file and a token in the environment |
| A wrapper command | Any command in a pipeline | Slightly more setup, least repetition |
The wrapper is worth showing because it composes:
with_alert() {
"$@" || curl -fsS https://ayeping.com/@you \
-H "Authorization: Bearer $AYEPING_TOKEN" \
-d "failed: $* on $(hostname)"
}
with_alert rsync -a /data/ backup:/data/
Errors you will meet, and what they mean
AyePing returns JSON error codes with distinct statuses, which makes a wrapper easy to branch on:
invalid_body(400): a field broke a rule, usually a title over 100 characters or with a newline.unauthorized(401): a wrong token, or a token that belongs to another username.quota_exhausted(402): the allowance is spent; the app sends one push a day about it.token_paused(403): someone paused the token on the Tokens page.body_too_large(413): the payload went past 32 KB.rate_limited(429): over the hourly cap, which runs 1 to 3,600 requests with 60 as the default.
The 400 case is the one that bites shell users, because an unquoted variable or a stray newline turns a title into an invalid field.
Keeping the request out of logs
Shell history and CI logs are the two places tokens leak. Three habits cover most of it:
- Read the token from the environment, never from an argument.
- Avoid
set -xaround the curl call, or the header lands in the log. - Use one token per machine so a leak can be revoked without touching the rest.
A token can send pings to its owner and nothing else, so the blast radius of a leak is small. It is still a credential, and the Tokens page exists so you can retire it.
Body limits worth designing around
Long error output does not belong in a title. Trim it, or send JSON with a message field of up to 2,000 characters and put the full log somewhere it can be opened.
| Field | Limit |
|---|---|
title |
1 to 100 characters, one line |
message |
Up to 2,000 characters, Markdown |
label.text |
1 to 20 characters |
| Whole body | 32 KB |
The habit that keeps it useful
Send only on failure. A script that reports success every night becomes background noise within a week, and the one night it genuinely breaks, nobody looks. Silence should mean healthy, and a ping should mean something needs a person.
FAQ
Does the script need curl installed?
The examples use curl because it is present on nearly every Linux and macOS host. Any HTTP client works, including Python's standard library.
Can I send a notification with no JSON at all?
Yes. Any body that does not begin with { is treated as the title, which is why a quoted string is enough.
What if the machine has no outbound internet?
Then the alert cannot be sent from that machine. Many teams route the failure through a hub that does have access.