Dokumentation

Zum Senden an Honk brauchst du einen einzigen Endpunkt, und diese Seite beschreibt ihn vollständig. Die Bibliotheken verpacken dieselbe Anfrage und bringen automatische Retries und Helfer mit.

Schnellstart

Ein Konto bekommen

Honk gibt es vorerst nur auf Einladung. Fordere Zugang an: Die Einladung kommt per E-Mail, und du meldest dich mit einem 6-stelligen Code an.
Projekt und Schlüssel anlegen

Öffne in der Web-App Projekte, leg ein Projekt an und erstelle dann im Tab Schlüssel einen Ingest-Schlüssel. Der Schlüssel (honk_…) wird nur einmal angezeigt, speichere ihn also gleich an einem sicheren Ort.

Ein Ereignis senden

Sende JSON mit dem Schlüssel als Bearer-Token. 202 heißt: Honk hat das Ereignis gespeichert.

Terminal

curl -sS https://honk-me.app/v1/messages \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Idempotency-Key: backup-$(date +%Y%m%d)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup failed",
    "message": "pg_dump exited with 1",
    "severity": "long",
    "group_key": "db/backup",
    "event_type": "problem"
  }'
# → 202 {"id":"msg_…","status":"accepted","duplicate":false,"received_at":"…"}

Den Push bekommen

Installiere Honk für iPhone oder aktiviere Mitteilungen in der Web-App unter Geräte. Tippe dann auf „Hup mich an“, um einen Test zu senden.

Die Anfrage

POST https://honk-me.app/v1/messages mit Content-Type: application/json und Authorization: Bearer <ingestion key>. Unbekannte Felder werden mit 422 abgelehnt. Der Body darf bis zu 16 KiB groß sein.

Felder

message: Pflichtfeld. 1 bis 8192 Byte UTF-8; Zeilenumbrüche bleiben erhalten.
title: Eine Zeile, bis zu 160 Zeichen. Standard: die erste Zeile der Nachricht.
severity: info, success, warning, error, critical oder die Hupen-Namen light, beep, loud, long, blast. Standard: info.
priority: low, normal, high oder urgent. Standard: normal. Für urgent brauchst du einen Schlüssel, der das erlaubt.
group_key: Bis zu 128 Zeichen. Ereignisse mit demselben Schlüssel (und demselben Projekt, derselben Umgebung, Quelle und demselben Kanal) bilden eine Gruppe.
event_type: event, problem oder recovery. Eine Entwarnung braucht einen group_key und schließt das offene Problem.
source , environment , channel: Bis zu 64, 32 und 64 Zeichen. Standard: api, default und general.
category: infrastructure, security, backups, deployments, payments, customers, sales, automation, personal oder other.
url: Ein https://-Link, angezeigt als „Link öffnen“. Er öffnet sich nur, wenn du darauf tippst.
image_url: Ein https://-Bild, das der Server abruft und mit der Mitteilung anzeigt (bis 1 MB bei Free, 5 MB bei Pro und Team).
actions: Bis zu 3 Buttons in der angezeigten Reihenfolge (der erste ist der wichtigste), zum Beispiel [{"title": "Reply by email", "url": "mailto:[email protected]"}, {"title": "Call", "url": "tel:+12025550147"}]. Ein Titel hat 1 bis 40 Zeichen; eine URL beginnt mit https://, mailto:, tel: oder sms: und öffnet sich nur, wenn du auf ihren Button tippst.
metadata: Bis zu 16 Schlüssel mit Werten vom Typ String, Zahl oder Boolean. Regeln können darauf prüfen.
occurred_at: Wann es an der Quelle passiert ist, als Zeitstempel nach RFC 3339.
ttl_seconds: Wie lange ein Push noch zugestellt werden darf: 60 bis 86400 Sekunden. Standard: 3600.
source_sequence: Eine steigende Zahl pro Quelle, damit eine verspätete Entwarnung nie ein neueres Problem schließt.

Antworten

202	Gespeichert. `{ "id", "status": "accepted", "duplicate", "received_at" }`. Das heißt nicht, dass das Ereignis gepusht oder gelesen wurde.
401	`invalid_key`: Der Schlüssel ist falsch oder widerrufen.
403	`priority_not_allowed`, `project_suspended` oder `workspace_suspended`.
409	`idempotency_conflict`: Derselbe Schlüssel wurde mit anderen Daten verwendet.
413, 415, 422	Zu groß, kein JSON oder ungültig: `error.fields` listet jedes Problem auf.
429	`quota_exceeded` (das tägliche Nachrichtenlimit) oder `rate_limited`, mit `Retry-After`.
503	Honk kann gerade nicht bestätigen, dass das Ereignis sicher gespeichert ist. Versuch es nach `Retry-After` mit demselben Schlüssel noch einmal.

Sicher wiederholen

Sende einen Idempotency-Key-Header (bis zu 128 druckbare ASCII-Zeichen), der für dasselbe Ereignis gleich bleibt, zum Beispiel deploy-4812-finished. Innerhalb von 24 Stunden liefert derselbe Schlüssel mit denselben Daten die ursprüngliche ID mit duplicate: true, derselbe Schlüssel mit anderen Daten ergibt 409. Wiederhole nur bei Netzwerkfehlern, 429 und 5xx, und halte dich an Retry-After. Die offiziellen Bibliotheken erledigen das alles für dich.

Schweregrad und die Honk-Skala

Die Hupen-Namen sind Aliasse. Honk speichert den Standardwert, "loud" und "warning" bedeuten also dasselbe, auch für die Idempotenz. error und critical werden immer mindestens mit der Priorität Hoch gepusht.

Leichtes Hupen	`info` · `light`
Tüt-tüt	`success` · `beep`
Lautes Hupen	`warning` · `loud`
Langes Hupen	`error` · `long`
Dauerhupen	`critical` · `blast`

Konzepte

Referenz

Die API zum Senden von Ereignissen als OpenAPI-3.1-Dokument (openapi.yaml)
Eine Übersicht dieser Doku als reiner Text, für Coding-Assistenten (llms.txt)
Die READMEs der Bibliotheken auf GitHub: Node.js , PHP / Laravel , Go + CLI , Swift , Kotlin / Java , Rust , n8n

Öffentlich ist nur die API zum Senden von Ereignissen. Der Rest dient den Honk-Apps und kann sich von Version zu Version ändern.