API-Dokumentation

Dein Endpoint

Jeder Endpoint, den du in der App anlegst, hat eine eindeutige URL:

https://api.webhooky.app/DEIN_KEY

Behandle den Key wie ein Passwort – wer die URL hat, kann dir Benachrichtigungen senden. Du kannst einen Endpoint jederzeit in der App löschen (und einen neuen erstellen).

Benachrichtigung senden

Sende einen HTTP-POST an deinen Endpoint. Der einfachste mögliche Aufruf:

curl -X POST "https://api.webhooky.app/DEIN_KEY"

Das stellt eine Push-Benachrichtigung mit dem Titel, Text, Sound und der Vibration zu, die du für den Endpoint in der App konfiguriert hast.

Titel, Nachricht, Sound & Vibration überschreiben

Sende beliebige dieser Felder im JSON-Body, um die Benachrichtigung pro Request zu steuern:

curl -X POST "https://api.webhooky.app/DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Neue Bestellung 🎉",
    "message": "Bestellung #1042 · 49,99 €",
    "sound": "cash_register",
    "vibrate": true
  }'

• title – ersetzt den Endpoint-Namen als Benachrichtigungstitel (max. 100 Zeichen).
• message – ersetzt den konfigurierten Text (max. 500 Zeichen).
• sound – spielt für diese Benachrichtigung einen anderen Sound. Akzeptiert jede Sound-ID aus der App (z. B. cash_register, error_1, doorbell_1, level_up_1); unbekannte IDs werden ignoriert.
• vibrate – true/false, überschreibt die Vibrationseinstellung des Endpoints für diese Benachrichtigung.
• Alle Felder sind optional und unabhängig; fehlende Felder fallen auf die Endpoint-Konfiguration in der App zurück.
• Längere Werte werden gekürzt, Whitespace wird normalisiert. Alle anderen JSON-Felder werden für die Anzeige ignoriert, aber mit dem Ereignis gespeichert, wenn Payload speichern aktiv ist.

Pro Endpoint bietet die App zusätzlich die Einstellungen Lautlos (kein Ton, keine Vibration, erscheint still) und Wichtig (Heads-up-Banner auf Android), die für alle Benachrichtigungen des Endpoints gelten.

Verfügbare Sound-IDs

Alle 40 Sound-IDs, die das sound-Feld akzeptiert (plus default für den Geräte-Standard):

Kategorie	IDs
Geld / Verkauf	cash_register, ka_ching (Katsching), coin, coin_clatter, coin_collision, coin_drop, coin_received, coin_win, casino_bling
Erfolg / Gaming	level_up_1, level_up_2, level_up_3, level_complete, bonus_reached, fireworks, uplifting_bells, bottles_clink
Fehler / Alarm	error_1, error_2, error_3, buzzer, game_over, car_horn_1, car_horn_2
Glocken / Türklingel	bell_ding, church_bell, doorbell_1, doorbell_2, doorbell_3, doorbell_4
Neutral	notification_1 … notification_5, news_ting
Spaß	cat_meow_1, cat_meow_2, dog_bark, rubber_duck

Jeden Sound kannst du in den Endpoint-Einstellungen der App probehören.

Beispiele in anderen Sprachen

# Python
import requests
requests.post("https://api.webhooky.app/DEIN_KEY",
              json={"title": "Hallo", "message": "aus Python"})

// JavaScript (Node 18+, Browser, Deno, Bun)
await fetch("https://api.webhooky.app/DEIN_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Hallo", message: "aus JS" }),
});

# PowerShell
Invoke-RestMethod -Method Post -Uri "https://api.webhooky.app/DEIN_KEY" `
  -ContentType "application/json" `
  -Body '{"title": "Hallo", "message": "aus PowerShell"}'

Testseite

Wenn du deine Endpoint-URL im Browser öffnest (HTTP-GET), erscheint eine Testseite mit Eingabefeldern für Titel, Nachricht und JSON-Payload plus Senden-Button. Praktisch, um dein Setup ohne Tools zu prüfen.

Antworten

Status	Bedeutung
200	Webhook angenommen und zugestellt. JSON-Body: {"success": true, "delivered": 1, "devices": 1, "message": "…"}
200	Webhook angenommen, aber nicht zugestellt: Gratis-Limit erreicht (100 Benachrichtigungen). Im JSON-Body steht "reason": "free_limit_reached", zusätzlich kommt der Header X-Webhooky-Limit: free-limit-reached. Upgrade auf Premium in der App.
400	Kein Key in der URL.
404	Key nicht gefunden – Endpoint wurde gelöscht oder die URL ist falsch.
405	Methode nicht erlaubt – nur GET und POST werden unterstützt.

Ist das Gratis-Limit erreicht, antwortet der Endpoint trotzdem mit 200, damit Webhook-Absender nicht erneut zustellen – mit diesem JSON-Body:

{ "success": false, "accepted": true, "delivered": 0, "reason": "free_limit_reached", "message": "…" }

Warum 200 und kein Fehler? Viele Webhook-Absender (z. B. Stripe, Shopify) werten Nicht-2xx-Antworten als Fehlschlag, wiederholen die Zustellung immer wieder und deaktivieren den Webhook womöglich irgendwann. Webhooky nimmt den Request deshalb immer an und meldet das Limit im Body. Prüfe success oder den Header X-Webhooky-Limit, wenn du den Endpoint aus eigenem Code aufrufst.

Zustellung & Limits

• Benachrichtigungen werden über FCM/APNs an alle Geräte deines Accounts zugestellt, meist in unter einer Sekunde.
• Der Gratis-Plan enthält insgesamt 100 Benachrichtigungen und einen Endpoint; Premium hebt beide Limits auf.
• Ereignisse landen im Verlauf in der App. Der Request-Payload wird nur gespeichert, wenn du Payload speichern für den Endpoint aktivierst.
• Es gibt kein festes Rate-Limit, aber Bursts können von den Push-Providern gedrosselt werden. Ein Ereignis = eine Benachrichtigung (pro Gerät dedupliziert).

Content-Types, CORS & Payload-Größe

JSON (application/json) wird empfohlen. Form-Posts (application/x-www-form-urlencoded) und Raw-Text-Bodies werden ebenfalls akzeptiert – wenn sich ein JSON-Objekt mit title/message finden lässt, wird es verwendet.

• CORS ist aktiviert (Access-Control-Allow-Origin: *) – du kannst deinen Endpoint direkt aus Browser-JavaScript aufrufen.
• Payloads klein halten. Nur title/message/sound/vibrate beeinflussen die Benachrichtigung; der Rest des Bodys wird nur bei aktivem Payload speichern aufbewahrt. Ein paar Kilobyte genügen völlig.

Maschinenlesbare Spezifikation

Eine OpenAPI-3.1-Beschreibung der API liegt unter webhooky.app/openapi.yaml – praktisch für API-Clients, Code-Generatoren und KI-Coding-Tools.