Webhooky für KI-Agenten

Mit KI einrichten

Füg das in Claude, ChatGPT, Cursor oder einen beliebigen Coding-Agenten ein und sag dann, was die Benachrichtigung auslösen soll. Ersetz DEIN_KEY durch den Key aus deiner Endpunkt-URL in der Webhooky-App.

Ich nutze Webhooky für Push-Benachrichtigungen aufs Handy.

Endpunkt: POST https://api.webhooky.app/DEIN_KEY
Auth: keine - die URL ist alles, es gibt keinen separaten Key zu verwalten.
      Sie kann ausschließlich eine Benachrichtigung auslösen: nichts lesen,
      kein Konto berühren, keine Daten preisgeben. Halte sie aus öffentlichen
      Repos heraus; wird sie bekannt, lösch den Endpunkt und leg einen neuen an.
Body: optionales JSON, alle Felder optional.
      title    String, max. 100 Zeichen - Titel der Benachrichtigung
      message  String, max. 500 Zeichen - Text der Benachrichtigung
      sound    String                   - eine Sound-ID, siehe unten
      vibrate  Boolean                  - überschreibt die Vibrationseinstellung
      Jedes weggelassene Feld fällt auf den am Endpunkt eingestellten
      Standardwert zurück. Zusätzliche Felder werden für die Anzeige ignoriert.
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
Antwort: bei gültigem Key immer HTTP 200, mit JSON-Body.
      {"success": true, "delivered": 1} wenn die Benachrichtigung rausging.
      {"success": false, "accepted": true, "reason": "free_limit_reached",
       "period": "2026-10"} wenn die 100 Benachrichtigungen des Gratis-Tarifs
      für diesen Kalendermonat aufgebraucht sind. Das Kontingent füllt sich am
      Monatsanfang wieder auf. Die 200 ist Absicht, damit Absender, die bei
      Fehlern wiederholen oder sich selbst deaktivieren, nicht stolpern.
      404 heißt, der Key ist falsch oder der Endpunkt wurde gelöscht.
Vollständige Spec: https://webhooky.app/openapi.yaml

Bitte ergänze in meinem Code eine Benachrichtigung für:

Der Prompt schreibt das Fallback-Verhalten und die 200er-Antwort bewusst aus – das sind die beiden Dinge, die ein Agent sonst falsch rät.

Der Vertrag in Kurzform

Ein Webhooky-Endpunkt ist eine URL, die einen HTTP-POST annimmt und daraus eine Push-Benachrichtigung auf allen Geräten macht, die bei diesem Konto angemeldet sind. Kein Konto anzulegen, keinen Key auszustellen, kein OAuth-Flow – die URL ist alles.

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

Die drei Verhaltensweisen, auf die es bei einer Integration ankommt

• Ein beliebiges Payload funktioniert. Fehlt im Body title oder message, nutzt die Benachrichtigung Titel, Text und Sound vom Endpunkt. Genau deshalb kann ein fremder Webhook – Stripe, GitHub, Etsy, WooCommerce – direkt auf eine Webhooky-URL zeigen, ohne etwas dazwischen, das das Payload umformt.
• Bei gültigem Key antwortet er immer mit 200, auch wenn das Gratis-Limit erreicht ist. Das zählt, weil Absender sich bei Fehlern schlecht verhalten: WooCommerce deaktiviert einen Webhook nach fünf Fehlschlägen in Folge, PayPal wiederholt bis zu 25 Mal über drei Tage, Stripe wiederholt mit Backoff drei Tage lang.
• Signaturen werden nicht geprüft. Jeder POST an die URL wird angenommen. Wenn ein Absender seine Zustellungen signiert und diese Prüfung dir wichtig ist, nimm den Webhook in deinem eigenen Handler entgegen, prüf dort und schick eine formatierte Nachricht an Webhooky weiter.

Drei Integrationsformen

Praktisch jede echte Integration ist eine davon.

1. Fremden Webhook direkt auf den Endpunkt richten

Kein Code. Füg die Webhooky-URL dort ein, wo der Dienst nach einer Callback- oder Payload-URL fragt. Die Benachrichtigung nutzt den am Endpunkt eingestellten Text. Richtig, wenn du erfahren willst, dass etwas passiert ist, und die Details nicht brauchst.

2. Aus eigenem Code aufrufen

# Python
import os, requests
requests.post(os.environ["WEBHOOKY_URL"], json={
    "title": "❌ Job fehlgeschlagen",
    "message": f"{job_name} beendet mit {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 fertig", sound: "level_up_2" }),
});

Halte es nicht-blockierend und lass eine fehlgeschlagene Benachrichtigung nie das kaputtmachen, worüber sie berichten sollte – kurzes Timeout, gekapselt, Fehler ignorieren.

3. Entgegennehmen, anreichern, weiterschicken

Nimm den fremden Webhook im eigenen Handler entgegen, prüf die Signatur, zieh die Felder heraus, die es laut zu sagen lohnt, und schick eine formatierte Nachricht. Quittiere dem Absender, bevor du arbeitest – die meisten werten einen langsamen Endpunkt als fehlgeschlagene Zustellung.

export async function handler(req, res) {
  res.sendStatus(200);                        // erst quittieren
  // ... Signatur prüfen, Payload parsen ...
  await fetch(process.env.WEBHOOKY_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title, message, sound: "cash_register" }),
  });
}

Den richtigen Sound wählen

Es gibt 40, und die Wahl trägt Bedeutung – der ganze Sinn des Produkts ist, Ereignisse zu unterscheiden, ohne sie zu lesen. Sinnvolle Vorgaben für einen Agenten: cash_register oder ka_ching für Umsatz, level_up_2 für Erfolg oder einen fertigen Job, buzzer oder error_1 für einen Fehlschlag, notification_1 wenn es rein informativ ist. Die verbindliche Liste steht aufgezählt in der OpenAPI-Spec, und jeder Sound lässt sich in der App anhören.

Oder gleich als MCP-Tool

Wenn dein Client das Model Context Protocol spricht, gibt es einen Server – webhooky-mcp –, der den Endpunkt zu einem Werkzeug macht. Die KI benachrichtigt dein Handy dann selbst, statt Code zu schreiben, der es später tut.

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

Für Claude Desktop, Cursor, Zed und den Rest dasselbe als Konfiguration:

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

Zwei Tools: send_notification (title, message, sound, vibrate) und list_sounds, das die 40 Sounds nach Bedeutung gruppiert, damit das Modell einen passenden wählt statt aus einer ID zu raten. Der Endpunkt-Key wird ausschließlich aus der Umgebung gelesen und nie als Tool-Argument angenommen – ein Modell lässt sich also nicht dazu überreden, woanders hinzusenden, und der Key bleibt aus dem Gesprächsverlauf heraus.

Maschinenlesbare Quellen

• /openapi.yaml – OpenAPI 3.1, die verbindliche Beschreibung: jede Sound-ID, jede Antwortform.
• /llms.txt – eine Karte dieser Website für Sprachmodelle, nach der llms.txt-Konvention.
• /de/docs – dieselbe API für menschliche Leser, mit mehr Beispielen.
• webhooky-mcp – der MCP-Server auf npm.

Limits und Fehlerfälle, die man kennen sollte

• Der Gratis-Tarif umfasst 100 Benachrichtigungen pro Kalendermonat (UTC) über bis zu 3 Endpunkte. Ist das Kontingent aufgebraucht, liefern Anfragen weiterhin 200 mit reason: free_limit_reached und der betroffenen period, zugestellt wird nichts. Am Monatsanfang füllt es sich wieder auf; Premium hebt das Limit ganz auf.
• Bei 90 und bei 100 Benachrichtigungen gehen jeden Monat Warnungen raus, das Limit ist also nie eine stille Überraschung.
• title wird bei 100 Zeichen gekürzt, message bei 500.
• Eine unbekannte sound-ID wird ignoriert statt abgelehnt – es greift der Standard des Endpunkts.
• Eine 404 heißt, der Key ist falsch oder der Endpunkt wurde in der App gelöscht. Es wird nichts zwischengespeichert.
• Es gibt keine Lese-API. Webhooky sendet Benachrichtigungen, es stellt keinen Historien-Endpunkt bereit. Die Historie liegt in der App.