API-Referenz
Ein Endpunkt, eine POST-Anfrage. Sende JSON an die Webhook-URL deines Channels, und wir kümmern uns um Benachrichtigungen, Formatierung und Zustellung.
Alert senden
Löst einen neuen Alert in einem bestimmten Channel aus. Das ist der wichtigste Endpunkt, um Benachrichtigungen aus deiner App zu senden.
curl -X POST https://zenhook.dev/api/webhook/abc123def456 \
-H "Content-Type: application/json" \
-d '{
"title": "Neue Registrierung",
"level": "success",
"emoji": "🎉",
"source": "Meine App",
"actor": {
"id": "42",
"name": "Jane Doe",
"email": "[email protected]",
"plan": "Pro"
},
"linkUrl": "https://myapp.com/admin/users/42",
"linkText": "Profil ansehen"
}'Pfadparameter
Anfrage-Body
info, success, warning, error. Standard ist info."🚀"), einen Namen ("rocket"), oder einen Shortcode (":rocket:"). Namen und Shortcodes werden beim Empfang übersetzt. Unbekannte Namen werden verworfen, nicht als Text angezeigt. Bekannte Namen: rocket · siren · warning · check · cross · fire · bug · zap · bell · tada · sparkles · envelope · chat · phone · megaphone · wave · eyes · heart · thumbsup · office · door · house · factory · lock · unlock · key · link · package · gear · wrench · shield · money · chart · clock · hourglass · flag · star · target · pin · tag · computer · server · database · cloud · bulb · gem · anchor · pick · bank.{ name, email, id, plan, company, location, avatarUrl, url }, einen beliebigen Teil davon oder nur einen String. Auch als user akzeptiert. Allein aus einer E-Mail ergänzt Zenhook den Anzeigenamen, die Initialen, die Firma hinter einer Firmendomain und den Gravatar, falls die Person einen hat.label und value. name wird anstelle von label akzeptiert, und ein Wert darf eine Zahl oder ein Boolean sein.linkUrl gesetzt ist.Fehler sind RFC 9457Problem-Dokumente, ausgeliefert als application/problem+json. Verzweige nach type, zeige title an. Das alte Feld error ist noch da, sodass ältere Integrationen weiter funktionieren.
{
"type": "https://zenhook.dev/problems/unknown-token",
"title": "Invalid webhook token",
"status": 404,
"error": "Invalid webhook token"
}Sende einen Header Idempotency-Key, und eine Wiederholung derselben Anfrage liefert 24 Stunden lang die erste Antwort, statt einen zweiten Alert zu erstellen. Die Wiederholung trägt Idempotency-Replayed: true. Eine Wiederholung, während die erste Anfrage noch läuft, bekommt eine 409 statt eines Duplikats. Das lohnt sich für alles, was bei einem Timeout neu versucht, vor allem für ein Deploy-Skript.
Antworten
Alert erhalten und zur Zustellung eingereiht. destination nennt den Workspace und den Channel, zu dem der Token gehört. So fällt eine falsch verdrahtete Integration schon in der Antwort auf und nicht erst Tage später im falschen Channel.
{
"success": true,
"alertId": "clx1234567890abcdef",
"destination": {
"workspace": { "id": "ws_...", "name": "Acme Corp" },
"channel": { "id": "ch_...", "name": "deploys", "slug": "deploys" }
}
}Nutze https://zenhook.dev/api/ für Integrationen. Der API-Alias www nimmt Anfragen ebenfalls an, ohne sie weiterzuleiten. Überschreitet ein Webhook oder ein Monitor-Heartbeat seine Anfragerate, enthält die Antwort 429 den Header Retry-After: Warte so viele Sekunden, bevor du es erneut versuchst. Das monatliche Kontingent an Ereignissen ist davon getrennt; eine Minute Warten erneuert es nicht.
Workflow-Benachrichtigungen
Ein Deploy oder Release ist ein Vorgang, nicht fünf Alerts. Füge einen Block workflow hinzu, und jeder POST mit derselben runId aktualisiert einen einzigen Alert an Ort und Stelle: Die Karte zeigt jeden Schritt live, und der Feed füllt sich nicht mit Zwischenständen.
# jeder POST eines Laufs trägt dieselbe runId
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
-H "Content-Type: application/json" \
-d '{
"title": "myapp deploy",
"workflow": {
"runId": "myapp-20260722-1015",
"state": "running",
"steps": [
{ "name": "test", "state": "done", "seconds": 46, "info": "716 Tests" },
{ "name": "build", "state": "running" },
{ "name": "deploy", "state": "pending" }
]
}
}'Zustände: Der Lauf ist running, passed oder failed; jeder Schritt ist pending, running, done, failed oder skipped. Sende jedes Mal das VOLLSTÄNDIGE Array steps; der Server ersetzt, er führt nie zusammen.
Benachrichtigungen: Der erste POST benachrichtigt (gestartet), laufende Updates sind still, und der Endzustand benachrichtigt einmal und holt den Alert als ungelesen wieder nach oben. Das Level des Alerts ergibt sich aus dem Zustand, ein fehlgeschlagener Lauf kann also nie Erfolg melden.
Zählung: Ein Vorgang ist ein abgerechnetes Ereignis, gezählt beim ersten POST. Updates sind kostenlos.
Bei einem Fehler: Gib workflow.error mit dem Ende des Logs mit; es erscheint auf der Karte, sodass sich der Fehler vom Handy aus untersuchen lässt.
Strukturierte Daten
Nutze das Array fields für zusätzliche Daten, die im Workspace und in E-Mail-Alerts angezeigt werden.
{
"title": "Build fehlgeschlagen",
"level": "error",
"fields": [
{ "label": "Branch", "value": "main" },
{ "label": "Commit", "value": "abc123f" },
{ "label": "Autor", "value": "John Smith" },
{ "label": "Fehler", "value": "npm install nach 300 s abgebrochen" }
],
"linkUrl": "https://github.com/org/repo/actions/runs/123",
"linkText": "Logs ansehen"
}Widgets im Feed
Es gibt nichts zu konfigurieren. Zenhook liest jede Art von Ereignis aus ihrer Geschichte und zeichnet das passende Widget. Eine Art von Ereignis ist ein Stream: derselbe Channel und derselbe Titel, Zahlen werden ignoriert, sodass Bestellung 1284 bezahlt und Bestellung 1285 bezahlt ein Stream sind. Halte den Titel stabil und schreibe, was sich ändert, in message, fields oder actor.
- Zähler, der Standard: jeder Stream, der sich wiederholt. Die Zahl des Tages, die Veränderung gegenüber gestern zur gleichen Stunde, Balken pro Stunde. Nichts zu senden.
- Pipeline: ein Titel mit deploy, build, release, pipeline oder CI, oder ein Block workflow. Die letzten Läufe und ihre Erfolgsquote. Sende
level: "error", wenn ein Lauf fehlschlägt. - Fehler:
level: "error". Wie oft heute, seit wann, die Nachricht und dein Link. - Geld: ein Feld namens Betrag, Preis, Summe, Umsatz, Amount, Price oder Total, etwa
49,00 €oder49 EUR. Die Tagessumme. - Person: ein
actor(oderuser). Wer, und wie viele heute und diese Woche. - Serie: ein Ereignis, das etwa einmal am Tag passiert, etwa ein Sync oder ein Backup. Tage in Folge.
- Ein einmaliges Ereignis bleibt eine Karte, auf der alles sichtbar ist. Öffne ein Widget, um seine Ereignisse zu lesen.
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
-H "Content-Type: application/json" \
-d '{
"title": "Zahlung erhalten",
"level": "success",
"actor": "[email protected]",
"fields": [{ "label": "Betrag", "value": "49,00 €" }]
}'Alerts wieder auslesen
Der Webhook-Endpunkt oben ist öffentlich und kann nur schreiben: Jeder mit dem Token des Channels kann dorthin senden. Um Alerts aufzulisten, als gelesen zu markieren oder eine Integration zu bauen, die sie verarbeitet, nutze die authentifizierte Lese-API mit einem Bearer-Token.