Workspace Webhooks: Isolierte Ereignisübermittlung für jeden Kunden auf Ihrer Plattform

Wenn du auf Firma.dev ein Multi-Tenant-SaaS betreibst, bist du wahrscheinlich schon an diese Wand gestoßen. Ein Webhook auf Unternehmensebene empfängt Ereignisse für jede Signing-Anfrage über jeden Workspace hinweg, und dein Backend muss sie an den richtigen Kunden weiterleiten. Funktioniert gut, wenn du beide Seiten kontrollierst. Zerfällt in dem Moment, in dem deine Kunden ihre eigenen Webhook-Endpunkte auf ihre eigenen Systeme zeigen lassen wollen.

Workspace-Webhooks lösen das. Jeder Workspace kann jetzt seine eigenen Webhook-Endpunkte mit unabhängigen Signatur-Secrets definieren, vollständig getrennt von Webhooks auf Unternehmensebene. Das ist der Baustein, der das Multi-Tenant-Modell von Firma.dev erst wirklich end-to-end zum Laufen bringt.

Das Multi-Tenant-Problem, das dadurch gelöst wird

Customer Workspaces haben dir schon immer partitionierte Bereiche für jeden Kunden auf deiner Plattform bereitgestellt. Jeder Workspace hat seine eigenen Vorlagen, seine eigene Envelope-Nutzung, seinen eigenen API-Schlüssel. Saubere Trennung. Aber bis jetzt war die Webhook-Zustellung die Ausnahme. Jedes Ereignis lief über einen einzigen Webhook auf Unternehmensebene, was bedeutete, dass deine Plattform bei Benachrichtigungen immer der Mittelsmann war.

Das ist für manche Architekturen in Ordnung. Für andere ist es ein K.-o.-Kriterium. Nimm eine Plattform, die es ihren Kunden erlaubt, ihre eigenen CRMs, ERPs oder Ticketing-Systeme anzubinden. Jeder Kunde möchte, dass Signing-Ereignisse direkt in seinen eigenen Stack gesendet werden. Oder denk an einen Reseller, der Endkunden eine echte Isolation über ihre Integrationen hinweg bietet. Oder an ein Dev-Team, das Staging-Workspaces Ereignisse an einen Test-Endpunkt senden lässt, während die Produktion an den echten Endpunkt sendet.

In all diesen Fällen muss der Webhook auf Workspace-Ebene leben, sonst bricht das ganze Modell zusammen.

Was pro Workspace verfügbar ist

Jeder Workspace bekommt jetzt das volle Webhook-Toolkit, auf ihn selbst beschränkt:

• Vollständiges CRUD für Webhook-Endpunkte

• Eigenes Signatur-Secret, mit einer 7-tägigen Kulanzfrist für die Rotation, wenn du es neu generierst

• Testzustellung, damit du die Einrichtung verifizieren kannst, ohne echte Ereignisse auszulösen

• Ein Ereignisprotokoll pro Workspace

• Ein Schalter „Unternehmens-Webhooks ignorieren“, wenn Workspace-Webhooks die Zustellung auf Unternehmensebene vollständig ersetzen sollen, statt parallel dazu zu laufen

Dieser letzte Schalter ist wichtiger, als er aussieht. Manche Teams wollen, dass sowohl Unternehmens- als auch Workspace-Webhooks ausgelöst werden, weil ihre Plattform weiterhin eine globale Sicht auf Ereignisse braucht, während Kunden ihre eigenen Feeds bekommen. Andere Teams wollen eine saubere Isolation, bei der Workspace-Webhooks die einzige Quelle der Wahrheit sind. Du entscheidest pro Workspace.

Sicherheit: SSRF-Schutz für alle Webhook-URLs

Ein Punkt, den Entwickler beachten sollten, die das evaluieren. Alle Webhook-URL-Validierungen enthalten jetzt SSRF-Schutz, der private IP-Bereiche, Cloud-Metadaten-Endpunkte und DNS-Rebinding-Versuche blockiert. Wenn du deine Kunden ihre eigenen Webhook-Endpunkte in von ihnen kontrollierten Workspaces konfigurieren lässt, ist das nicht optional. Ein Kunde könnte versehentlich (oder absichtlich) einen Webhook auf 169.254.169.254 oder eine interne IP zeigen lassen, und ohne SSRF-Schutz würdest du Anfragen aus der Infrastruktur von Firma in Ziele proxyen, die niemand erreichen sollte.

Das wird auf der Plattformebene gehandhabt, du musst also keine eigenen Schutzmechanismen bauen.

API-Oberfläche

Ein paar Ergänzungen auf der API-Seite:

• Der workspace_id-Parameter bei POST /webhooks und GET /webhooks, damit du Webhook-Operationen auf einen bestimmten Workspace eingrenzen kannst

• Neue Endpunkte für die Verwaltung von Webhook-Secrets für Workspaces: POST /workspaces/{id}/webhooks/rotate-secret und GET /workspaces/{id}/webhooks/secret-status

• Fünf neue Felder in der GET-Antwort des Workspaces, die den Webhook-Konfigurationsstatus abdecken

Die vollständigen Details stehen im API-Changelog für v1.15.0.

Wann Workspace-Webhooks statt Unternehmens-Webhooks verwenden

Kurzes mentales Modell:

Unternehmens-Webhooks sind für deine Plattform. Alles, was deine Kernanwendung über alle Kunden hinweg wissen muss, sollte über die Zustellung auf Unternehmensebene laufen. Abrechnungsereignisse, Compliance-Logging, Analysen, interne Workflows.

Workspace-Webhooks sind für deine Kunden. Alles, worauf die Systeme eines bestimmten Kunden reagieren müssen, sollte über die Zustellung auf Workspace-Ebene laufen. CRM-Updates, kundenspezifische Benachrichtigungen, Drittanbieter-Integrationen, die sie selbst eingerichtet haben.

Beides kann im selben Workspace koexistieren, oder du kannst einen Workspace vollständig von Unternehmens-Webhooks ausnehmen. Für die meisten Multi-Tenant-Plattformen ist das richtige Muster: Unternehmens-Webhooks für plattformkritische Ereignisse plus Workspace-Webhooks, die deine Kunden über deine UI konfigurieren.

Erste Schritte

Wenn du Customer Workspaces bereits verwendest, kannst du heute mit Workspace-Webhooks beginnen. Bestehende Webhook-Integrationen auf Unternehmensebene funktionieren genau wie zuvor weiter. Das ist rein ergänzend.

Leg kostenlos mit Firma.dev los, keine Kreditkarte erforderlich. 25 kostenlose Envelopes, keine Verträge, keine Mindestmengen und das vollständige Multi-Tenant-Toolkit einschließlich Customer Workspaces und Workspace-Webhooks vom ersten Tag an.