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:

  1. Read the token from the environment, never from an argument.
  2. Avoid set -x around the curl call, or the header lands in the log.
  3. 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.