Webhooks: Aus jeder HTTP-Anfrage wird eine Notiz

Jeder Workspace hatte schon drei Eingänge: die App, die CLI und einen KI-Assistenten über MCP. Alle drei setzen voraus, dass ein Mensch oder ein Assistent schreibt. Vieles, was sich aufzuheben lohnt, schreibt aber keiner von beiden: ein fehlgeschlagener Deploy, ein Kommentar in Figma, die wöchentliche Auszahlung, ein ausgefülltes Formular.

Notez v0.15.0 bringt den vierten Weg: eine Webhook-URL. Alles, was eine HTTP-Anfrage senden kann, legt jetzt eine Notiz an.

Eine URL, eine Zeile curl

Leg unter Einstellungen → Integrationen → Webhooks einen Webhook an, und Notez gibt dir eine URL. Mehr Einrichtung gibt es nicht:

curl -X POST "https://api.notez.dev/api/webhooks/notes/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy failed on main", "content": "## Details\n- commit abc123", "tags": ["alerts"]}'

Die Notiz erscheint mit ihren Tags unter der Notiz, die du als Ziel gewählt hast, in der Board-Spalte, die du ausgesucht hast. Tags, die du noch nie benutzt hast, werden sofort angelegt.

Absender, die dein Format nicht lernen

Ein sauberes JSON-Format funktioniert, solange du den Absender kontrollierst. GitHub, Stripe und Sentry ist egal, welches Format du gern hättest: Sie schicken ihren eigenen Payload, und aussuchen kannst du nur die URL.

Deshalb hat ein Webhook zwei Modi. Notez-Format prüft streng, weist Tippfehler ab und liefert Titel, Inhalt, Tags und Anhänge. Beliebiges JSON nimmt alles, was ankommt, und speichert es als formatierten Codeblock. Den Titel nimmt es aus dem Payload, wenn dieser ein title hat, sonst aus dem Namen des Webhooks. Keine Anfrage wird wegen unerwarteter Felder abgewiesen, und genau darum geht es.

Anhänge, auch die, von denen du nur einen Link hast

Eine Anfrage kann bis zu zehn Dateien mitbringen, auf drei Arten: als Datei-Upload, als Base64 im JSON oder als Link, den Notez für dich herunterlädt. Erst die dritte Art macht Automatisierungstools brauchbar, denn Zapier gibt dir einen Link zur Datei, nie die Bytes.

Herunterzuladen, worauf eine URL zeigt, ist allerdings auch der schnellste Weg zu einem Loch in der eigenen Infrastruktur. Eine Webhook-URL ist öffentlich, also könnte sonst jeder mit „lade diesen Link herunter“ meine Server auf interne Adressen richten und zurücklesen, was dort antwortet. Jeder Download löst deshalb zuerst die Adresse auf, verweigert private und interne Bereiche sowie die Metadaten-Adressen von Cloud-Anbietern, prüft nach jeder Weiterleitung erneut und verbindet sich nur mit der Adresse, die er schon geprüft hat. So kann eine zweite DNS-Antwort nach der Prüfung nichts Internes unterschieben. Dateien, die zu langsam laden, zu groß sind oder hinter einem Login liegen, werden zu Links in der Notiz, statt zu verschwinden.

Wiederholungen und die Notiz, die du nicht doppelt willst

Absender wiederholen eine Anfrage, wenn die Antwort zu lange dauert, und eine Wiederholung, die eine zweite Notiz anlegt, ist schlimmer als gar keine Notiz. Schick einen Header Idempotency-Key oder eine externalId im Body mit, dann liefert eine Wiederholung innerhalb von 24 Stunden die Notiz zurück, die es schon gibt. Die Delivery-ID von GitHub übernimmt Notez automatisch, also sind GitHubs Wiederholungen ohne jede Einrichtung sicher.

Signaturen: absichtlich optional

Die URL ist der Zugangsschlüssel, und URLs sickern durch: in Logs, Screenshots, geteilte Konfigurationen. Wenn der Absender seine Anfragen signieren kann, prüft Notez die Signatur und lehnt alles andere ab.

Ich habe die Prüfung optional gemacht, und das verdient eine Erklärung. Sie ist kein Schloss, über das ich bestimme, sondern die Kontrolle von etwas, das der Absender tun muss. GitHub signiert. Stripe signiert. Zapier, Kurzbefehle und die meisten Skripte können das nicht. Mit Pflicht zur Signatur wäre aus einer Funktion, die mit allem funktioniert, eine geworden, die mit drei Diensten funktioniert. Deshalb bleibt die URL die Grundlage, und die Signatur ist eine zweite Schicht für Absender, die sie unterstützen. Die Liste markiert die unsignierten Webhooks, damit der Kompromiss sichtbar bleibt und nicht in Vergessenheit gerät.

Ein Signatur-Secret ist einer der seltenen Zugangsschlüssel, die ich wieder auslesen können muss: Eine Signatur zu prüfen heißt, sie neu zu berechnen, also wird das Secret verschlüsselt statt gehasht. Dieser Unterschied ist wichtiger, als er klingt, und er hat in diesem Release noch etwas anderes verändert.

Bei der Gelegenheit: Schlüssel werden jetzt gehasht

Webhook-URLs werden als Hashes gespeichert, denn um ein Token wiederzuerkennen, muss man es nie reproduzieren. Die MCP- und CLI-Schlüssel, die ich früher gebaut hatte, lagen dagegen im Klartext, lesbar für jeden, der die Datenbank lesen konnte.

Jetzt sind auch sie gehasht. In der Praxis heißt das: Ein MCP-Schlüssel wird einmal angezeigt, wenn du ihn erzeugst, danach zeigt die Seite nur noch seine ersten paar Zeichen. Hast du ihn verloren, rotierst du ihn. Die CLI hat ihren Schlüssel ohnehin nie angezeigt.

Aus derselben Arbeit sind zwei kleinere Änderungen entstanden. Jeder Webhook erstellt Notizen im Namen der Person, die ihn angelegt hat. Entfernst du jemanden aus einem Workspace, werden deshalb jetzt auch seine Webhooks gelöscht, und keine URL überlebt ihren Besitzer. Außerdem schwärzt das Audit-Log, das die Eingaben jeder Änderung aufzeichnet, jetzt alles, was nach Zugangsdaten aussieht: Es hätte sonst Signatur-Secrets im Klartext direkt neben ihren verschlüsselten Kopien gespeichert.

Was du daran anschließen kannst

• GitHub – Issues, Deploys, fehlgeschlagene Workflows, mit eingeschalteter Signaturprüfung.

• Zapier oder Make – ein Schritt am Ende jeder Automatisierung, der das Ergebnis dort ablegt, wo du es findest.

• Cron und CI – nächtliche Backup-Berichte, Release Notes, eine Zusammenfassung, die sonst in einem Log läge, das niemand öffnet.

• Deine eigene App – Supportanfragen, Registrierungen, alles, was du neben deinen Notizen aufheben willst.

Notizen aus einem Webhook tragen das Badge WH, damit deine eigenen Texte nicht zwischen ihnen untergehen.

Alle Details, Limits und die Schritt-für-Schritt-Anleitung für GitHub stehen im Hilfeartikel zu Webhooks.

Weiterlesen

• Erste Schritte mit der Notez CLI – die Installationsbefehle für macOS, Linux und Windows, wo notez login seinen Schlüssel ablegt und wie du mit --json Skripte schreibst.

• Wie du als Entwickler ein Notizsystem aufbaust – vier Arten von Notizen, die sich lohnen, Festhalten in unter fünf Sekunden, keine Ordner und zehn Minuten Durchsicht pro Woche.

• Notizen direkt aus dem Terminal festhalten – drei Wege, in der Shell Notizen zu machen, von echo >> ~/notes.md bis zu einer CLI zum Festhalten, und wo jeder davon scheitert, wenn du die Notiz wiederfinden willst.