Webhooky for AI agents

Set up with AI

Paste this into Claude, ChatGPT, Cursor or any coding agent, then tell it what should trigger the notification. Replace YOUR_KEY with the key from your endpoint URL in the Webhooky app.

I use Webhooky to get push notifications on my phone.

Endpoint: POST https://api.webhooky.app/YOUR_KEY
Auth: none - the URL is the whole thing, there is no separate key to manage.
      It can only trigger a notification: it cannot read anything, reach an
      account or expose data. Keep it out of public repos; if it leaks, delete
      the endpoint in the app and make a new one.
Body: optional JSON, all fields optional.
      title    string, max 100 chars - notification title
      message  string, max 500 chars - notification text
      sound    string                - a sound id, see below
      vibrate  boolean               - overrides the endpoint's vibration setting
      Any omitted field falls back to the default configured on the endpoint.
      Any extra fields are ignored for display.
Sounds: cash_register, ka_ching, coin, coin_win, coin_drop, coin_received,
      coin_clatter, coin_collision, casino_bling, bonus_reached,
      level_up_1, level_up_2, level_up_3, level_complete, game_over,
      buzzer, error_1, error_2, error_3,
      notification_1, notification_2, notification_3, notification_4,
      notification_5, bell_ding, church_bell, news_ting, uplifting_bells,
      fireworks, doorbell_1, doorbell_2, doorbell_3, doorbell_4,
      car_horn_1, car_horn_2, dog_bark, cat_meow_1, cat_meow_2,
      rubber_duck, bottles_clink
Response: always HTTP 200 for a valid key, with a JSON body.
      {"success": true, "delivered": 1} when the notification went out.
      {"success": false, "accepted": true, "reason": "free_limit_reached",
       "period": "2026-10"} when the free plan's 100 notifications for that
      calendar month are used up. The quota resets at the start of the next
      month. The 200 is deliberate, so senders that retry or auto-disable on
      failure are not tripped. 404 means the key is wrong or the endpoint
      was deleted.
Full spec: https://webhooky.app/openapi.yaml

Please add a notification to my code for:

The prompt spells out the fallback behaviour and the 200 response on purpose – those are the two things an agent otherwise guesses wrong.

The contract, in short

A Webhooky endpoint is a URL that accepts an HTTP POST and turns it into a push notification on every device signed in to that account. No account to create, no key to issue, no OAuth flow – the URL is the whole thing.

curl -X POST https://api.webhooky.app/YOUR_KEY \
  -H "Content-Type: application/json" \
  -d '{"title":"Deploy finished","message":"v2.1.0 is live","sound":"level_up_2"}'

The three behaviours that matter for an integration

• An arbitrary payload works. If the body has no title or message, the notification uses the title, text and sound configured on the endpoint. That's why a third-party webhook – Stripe, GitHub, Etsy, WooCommerce – can point at a Webhooky URL directly, with nothing in between to reshape the payload.
• It always answers 200 for a valid key, including when the free limit is reached. This matters because senders behave badly on failure: WooCommerce disables a webhook after five consecutive failures, PayPal retries up to 25 times over three days, Stripe retries with backoff for three days.
• It does not verify signatures. Any POST to the URL is accepted. If a sender signs its deliveries and that verification matters, terminate the webhook in your own handler, verify there, and forward a formatted message to Webhooky.

Three integration shapes

Almost every real integration is one of these.

1. Point a third-party webhook straight at the endpoint

No code. Paste the Webhooky URL wherever the service asks for a callback or payload URL. The notification uses the endpoint's configured text. Right when you want to be told that something happened and don't need the details.

2. Call it from your own code

# Python
import os, requests
requests.post(os.environ["WEBHOOKY_URL"], json={
    "title": "❌ Job failed",
    "message": f"{job_name} exited with {code}",
    "sound": "buzzer",
}, timeout=5)

// Node.js
await fetch(process.env.WEBHOOKY_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "✅ Backup done", sound: "level_up_2" }),
});

Keep it non-blocking and never let a notification failure break the thing it was reporting on – short timeout, wrapped, errors ignored.

3. Receive, enrich, forward

Take the third-party webhook in your own handler, verify its signature, pull out the fields worth saying out loud, and POST a formatted message. Acknowledge the sender before doing the work, because most senders count a slow endpoint as a failed delivery.

export async function handler(req, res) {
  res.sendStatus(200);                        // ack first
  // ... verify signature, parse payload ...
  await fetch(process.env.WEBHOOKY_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title, message, sound: "cash_register" }),
  });
}

Choosing a sound

There are 40, and the choice carries meaning – the whole point of the product is telling events apart without reading them. Sensible defaults for an agent: cash_register or ka_ching for revenue, level_up_2 for a success or a finished job, buzzer or error_1 for a failure, notification_1 when it's merely informational. The authoritative list is enumerated in the OpenAPI spec, and every sound can be played in the app.

Use it as an MCP tool instead

If your client speaks the Model Context Protocol, there is a server – webhooky-mcp – that turns the endpoint into a tool. The assistant then notifies your phone itself, rather than writing code that does it later.

claude mcp add webhooky \
  -e WEBHOOKY_URL=https://api.webhooky.app/YOUR_KEY \
  -- npx -y webhooky-mcp

For Claude Desktop, Cursor, Zed and the rest, the same thing as config:

{
  "mcpServers": {
    "webhooky": {
      "command": "npx",
      "args": ["-y", "webhooky-mcp"],
      "env": { "WEBHOOKY_URL": "https://api.webhooky.app/YOUR_KEY" }
    }
  }
}

Two tools: send_notification (title, message, sound, vibrate) and list_sounds, which groups the 40 sounds by meaning so the model picks one that fits rather than guessing from an id. The endpoint key is read from the environment only, never accepted as a tool argument – a model cannot be talked into sending somewhere else, and the key stays out of the transcript.

Machine-readable sources

• /openapi.yaml – OpenAPI 3.1, the authoritative description: every sound id, every response shape.
• /llms.txt – a map of this site for language models, following the llms.txt convention.
• /docs – the same API for human readers, with more examples.
• webhooky-mcp – the MCP server on npm.

Limits and failure modes worth knowing

• The free plan covers 100 notifications per calendar month (UTC) across up to 3 endpoints. Once used up, requests still return 200 with reason: free_limit_reached and the period it applies to, and nothing is delivered. The quota refills at the start of the next month; Premium removes the limit entirely.
• Alerts go out at 90 and at 100 notifications each month, so the limit is never a silent surprise.
• title is truncated at 100 characters, message at 500.
• An unknown sound id is ignored rather than rejected – the endpoint's default is used.
• A 404 means the key is wrong or the endpoint was deleted in the app. Nothing is queued.
• There is no read API. Webhooky sends notifications; it does not expose a history endpoint. The history lives in the app.