osFoundry / Platform
Eingehende Webhooks
Eine URL pro App oder Workspace zum Empfangen von Ereignissen. Signaturprüfung integriert.
Was es ist
Inbound-Webhooks geben osFoundry eine Empfangsadresse für die Außenwelt. Sie erzeugen ein Token mit Gültigkeit für eine bestimmte App, Instanz und einen bestimmten Kanal, und osFoundry liefert eine eigene URL unter /api/v1/webhooks/inbound/{id} zurück. Externe Systeme (Stripe, GitHub, Zapier, eine CI-Pipeline, Ihr eigenes Backend) senden JSON per POST an diese URL, und das Event landet im gewählten Echtzeit-Kanal, wo Ihr Chat, Ihre Agenten und Ihre Apps darauf reagieren können. Es gibt kein Polling und keinen separaten Integrationsserver zu betreiben: Der Endpunkt ist die Integration.\n\nDie Signaturprüfung ist eingebaut, nicht nachträglich aufgesetzt. Jedes Token trägt ein HMAC-SHA256-Signing-Secret, das genau einmal beim Erzeugen angezeigt wird. Der Absender berechnet eine Signatur über das Payload und übergibt sie im Header X-OsFoundry-Signature; osFoundry validiert sie bei jeder Anfrage und weist alles zurück, was unsigniert oder unterwegs verändert wurde. Wenn Sie den Schlüssel eines Absenders wechseln müssen, öffnet die Rotation des Secrets ein 7-tägiges Kulanzfenster, in dem das vorherige Secret weiterhin gültig bleibt, sodass die Rotation nie ein laufendes Event verwirft. Ein Token zu widerrufen wirkt sofort: Der Endpunkt gibt augenblicklich 401 zurück, was der schnelle Weg bei einem geleakten Secret oder einer stillgelegten Integration ist.\n\nWeil dies innerhalb des BYOK-Desktop-Workspaces von osFoundry läuft, kann ein eingehendes Event dieselben Agenten, Apps und Wissensbestände auslösen, mit denen Sie ohnehin arbeiten, ohne Integrationsabgabe pro Sitz und ohne Umweg Ihrer Daten über einen fremden Vermittler. Jedes Token protokolliert seinen letzten Nutzungszeitpunkt und die Anfragezahl der letzten 24 Stunden, sodass Sie sehen, welche Absender aktiv sind, und die Plattform behält die letzten 100 eingehenden Anfragen zum erneuten Senden vor. Das macht aus dem Debuggen von Webhooks statt Raterei ein erneutes Ausführen des tatsächlichen Payloads.
Wichtige Funktionen
- Erzeugen Sie eine eigene Empfangs-URL pro App, Instanz und Kanal: Externe Systeme senden JSON-Events per POST direkt an diesen Endpunkt unter /api/v1/webhooks/inbound/{id}
- Jede Anfrage wird gegen eine HMAC-SHA256-Signatur im Header X-OsFoundry-Signature geprüft, sodass unsignierte oder manipulierte Payloads abgewiesen werden, bevor sie Ihren Kanal erreichen
- Rotieren Sie ein Signing-Secret mit einem 7-tägigen Kulanzfenster, in dem das alte Secret weiterhin validiert, um Absender-Schlüssel zu wechseln, ohne Events zu verlieren
- Widerrufen Sie ein Token sofort: Der Endpunkt gibt im Moment des Widerrufs 401 zurück und kappt einen geleakten oder ausgemusterten Absender
- Sehen Sie pro Token den letzten Nutzungszeitpunkt und die Anfragezahl der letzten 24 Stunden, und senden Sie die letzten 100 eingehenden Anfragen aus den Trigger-Einstellungen erneut, wenn Sie eine Zustellung debuggen müssen
Anwendungsfälle
- Entwickler, der Stripe anbindet: Er erzeugt ein Token mit Gültigkeit für einen Abrechnungskanal, richtet Stripes Webhook auf die URL und lässt osFoundry jeden POST abweisen, dessen HMAC-Signatur nicht passt, bevor er einen Agenten erreicht
- Ops-Engineer mit geleaktem Secret: Er widerruft das betroffene Token für ein sofortiges 401 und erzeugt ein frisches, ohne die anderen Integrationen lahmzulegen, die den Workspace speisen
- Automatisierungsentwickler, der eine CI-Pipeline anbindet: Er sendet Build-Status-Events per POST in einen Kanal, in dem ein Agent Fehlschläge triagiert, und nutzt das Replay der letzten 100 Anfragen, um die Payload-Form zu debuggen
Häufig gestellte Fragen
Wie prüft osFoundry, dass ein eingehender Webhook echt ist?
Jedes Inbound-Token hat ein HMAC-SHA256-Signing-Secret. Der Absender berechnet eine Signatur über den Anfrage-Body und sendet sie im Header X-OsFoundry-Signature, und osFoundry berechnet sie bei jeder Anfrage neu und vergleicht sie. Anfragen mit fehlender oder ungültiger Signatur werden abgewiesen, sodass nur ein System mit dem Secret in Ihren Kanal veröffentlichen kann. Das Secret wird beim Erzeugen genau einmal angezeigt: Speichern Sie es dann, denn es wird später nicht erneut ausgegeben.
Was passiert mit laufenden Events, wenn ich ein Token rotiere oder widerrufe?
Die Rotation gibt Ihnen ein 7-tägiges Kulanzfenster, in dem sowohl das neue als auch das vorherige Secret validieren, sodass Sie jeden Absender aktualisieren können, ohne beim Umstieg Events zu verlieren. Der Widerruf ist bewusst das Gegenteil: Der Endpunkt gibt sofort 401 zurück und kappt den Absender augenblicklich, was Sie genau dann wollen, wenn ein Secret leakt oder eine Integration stillgelegt wird.
Bekomme ich eine einzige Webhook-URL für alles, oder kann ich sie eingrenzen?
Jedes Token ist auf eine bestimmte App, Instanz und einen bestimmten Kanal begrenzt und erzeugt seine eigene URL unter /api/v1/webhooks/inbound/{id}. Das heißt, ein Absender kann nicht in einen Kanal veröffentlichen, für den er keine Berechtigung hat, und Sie können eine einzelne Integration widerrufen oder rotieren, ohne die anderen anzurühren. Jedes Token meldet zudem seinen letzten Nutzungszeitpunkt und die Anfragezahl der letzten 24 Stunden, sodass Sie erkennen, welche Endpunkte tatsächlich Traffic empfangen.