23 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 34 | Public API & Webhooks | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
requirements-pur |
Modul 34 — Public API & Webhooks
Detail-Spec gemäß LP-9. Phase-1-Basic. Read-API (GET) für Hauptentitäten + eingehende Webhooks für Lead-Push + ausgehende Webhooks als Automation-Engine-Action (M17). API-Key-Verwaltung kommt aus M27 Block E. OpenAPI-Doku auto-generiert. Voll-CRUD-API erst Phase 2 (bewusste Scope-Beschränkung).
Themenblöcke
A. Datenmodell (Logging und Webhook-Subscriptions)
B. Authentifizierung & Scopes (Verweis auf M27 Block E)
C. Read-API (GET-Endpoints für Hauptentitäten)
D. Eingehende Webhooks (Lead-Push)
E. Ausgehende Webhooks (Subscription-Modell)
F. Allgemeine Event-Ingestion
G. OpenAPI-Doku
H. Rate-Limiting
I. Versionierung & Stabilität
J. Permissions / Scope-Mapping
K. Phase 2
Block A — Datenmodell
IntegrationApiRequest
Audit-Log aller eingehenden API-Requests. Tenant-scoped.
id,tenant_id,created_atapi_key_id(FK auf ApiKey aus M27 — nullable bei unauth Requests)route_pattern(z.B./api/v1/contacts/:id)http_method(GET / POST / PUT / DELETE)query_params(JSONB — sanitized)request_body_size_bytesresponse_status_code(Integer)response_size_bytesduration_msclient_ipuser_agenterror_message(nullable, Klartext)
Indizes:
(tenant_id, api_key_id, created_at DESC)— pro-Key-Logs(tenant_id, route_pattern, created_at DESC)— pro-Endpoint-Stats(tenant_id, response_status_code, created_at DESC)— Error-Monitoring
Retention: 90 Tage, danach gelöscht (außer 4xx/5xx → 180 Tage).
WebhookSubscription
Definition eines vom Tenant abonnierten ausgehenden Webhooks. Tenant-scoped.
id,tenant_id,created_at,updated_at,created_by_user_idname(interner Name)target_url(URL, an die ausgehende Events gesendet werden)secret_encrypted(für HMAC-Signatur)event_types[](Liste der abonnierten Events, z.B.contact.created,deal.stage_changed,project.completed)filter_definition(optional — JSONB für event-spezifische Filter)is_active(Boolean)failure_count_consecutive(Integer — Auto-Disable nach N Fehlern)last_success_at,last_failure_at,last_failure_reasonarchived_at
Indizes: (tenant_id, is_active, event_types) für Event-Dispatch.
WebhookDelivery
Pro Event-Auslösung pro Subscription ein Eintrag.
id,tenant_id,subscription_id,created_atevent_type,event_id(für Idempotenz beim Empfänger)payload(JSONB — finaler Body)status(Enum:pending | delivered | failed | exhausted | discarded)attempt_count(Integer, max. 5)last_attempt_at,delivered_atlast_response_status_code,last_response_body_excerpt(max. 500 Zeichen)
Indizes: (tenant_id, subscription_id, status), (status, last_attempt_at) für Retry-Worker.
WebhookDeliveryAttempt
Pro Versuch ein Audit-Eintrag.
id,tenant_id,delivery_id,attempted_atattempt_number(1..5)request_signature(HMAC-Hex, gespeichert für Diagnose)response_status_code(Integer, nullable bei Network-Error)response_body_excerpt(max. 500 Zeichen)response_time_mserror_text(Klartext bei Network/Timeout-Fehler)
Retention: 30 Tage.
IncomingWebhookIngestion
Logs der eingehenden Webhooks (Lead-Push, Form-Submissions, etc.). Tenant-scoped.
id,tenant_id,received_atslug(z.B.website-form-kontakt— vom Tenant definiert)source_kind(Enum:lead | form_submission | generic_event— Phase 1 only Lead-fokussiert)auth_method(Enum:api_key | hmac_signature | unauthenticated_with_token)payload(JSONB)processing_status(Enum:received | processing | done | failed | rejected_invalid_payload | rejected_auth | rejected_rate_limit)processed_at,error_textderived_lead_id/derived_contact_id(FK, nullable — was wurde erzeugt)client_ip,user_agent
Retention: 90 Tage erfolgreiche, 180 Tage fehlerhafte (für Diagnose).
Block B — Authentifizierung & Scopes
Authentifizierung-Methoden
Methode 1: API-Key-Bearer (Standard)
- Header:
Authorization: Bearer hg_<random_64_chars> - API-Key-Verwaltung in M27 Block E
- Pro Request: Loader prüft Key-Existenz, Scope, Tenant-Zuordnung, Aktiv-Status
Methode 2: HMAC-Signatur (für eingehende Webhooks)
- Header:
X-HiveGrid-Signature: sha256=<hex> - Body wird mit Webhook-Slug-Secret HMAC-SHA256 signiert
- Verifikation mit Constant-Time-Compare gegen Slug-spezifisches Secret
Methode 3: URL-Token (Fallback für Form-Webhooks)
- URL-Path enthält Token:
/api/v1/webhooks/incoming/{tenant}/{slug}?token=... - Mit Klartext-Warnung im UI: „URL-Token ist weniger sicher als API-Key — nur für Form-Anbieter ohne Header-Support nutzen"
Scope-Modell (kommt aus M27 Block E, hier konkretisiert)
| Scope | Erlaubt |
|---|---|
read_only |
Alle GET-Endpoints außer sensible Felder (Mails, HR, finanzielle Daten) |
read_full |
Alle GET-Endpoints inkl. sensible Daten |
webhook_inbound |
Eingehende Lead-/Form-Webhook-Endpoints — kein Read-Zugriff |
automation_trigger |
Auslösen von Automation-Triggern via API |
Scope-Mapping zu Endpoints
- Default Phase 1: 1 Key = 1 Scope
- Phase 2: Multi-Scope-Keys + granulare Scopes pro Modul
Klartext-Fehler
- 401 unauthorized: „API-Key fehlt oder ungültig. Header
Authorization: Bearer hg_...setzen." - 403 forbidden: „Dieser API-Key hat nicht die Berechtigung für diese Aktion. Erforderlicher Scope:
read_full." - 429 rate limit: „Rate-Limit erreicht: 1.000 Anfragen/Stunde. Reset um [timestamp]. Tenant-Admin kann Limit erhöhen."
Block C — Read-API (GET-Endpoints)
Endpoint-Übersicht
GET /api/v1/contacts → Liste Kontakte
GET /api/v1/contacts/:id → Einzelner Kontakt
GET /api/v1/companies → Liste Firmen
GET /api/v1/companies/:id → Einzelne Firma
GET /api/v1/deals → Liste Deals
GET /api/v1/deals/:id → Einzelner Deal
GET /api/v1/projects → Liste Projekte
GET /api/v1/projects/:id → Einzelnes Projekt
GET /api/v1/tasks → Liste Tasks
GET /api/v1/tasks/:id → Einzelner Task
GET /api/v1/leads → Liste Leads
GET /api/v1/leads/:id → Einzelner Lead
Gemeinsame Konventionen
Pagination (Cursor-basiert):
- Query-Param
cursor(opaque, base64-encoded) - Query-Param
limit(Default 50, max. 200) - Response enthält
meta.next_cursor(null wenn keine weiteren)
Filter:
- Per Query-Param, z.B.
?tag=newsletter&assignee_id=... - Multi-Value:
?tag=a&tag=b(OR-Logik) - Date-Range:
?created_at_gte=2026-01-01&created_at_lte=2026-12-31 - Custom-Felder:
?custom.heizungsanlage_modell=Vaillant
Sortierung:
- Query-Param
sort(z.B.sort=-updated_atfür absteigend,sort=last_namefür aufsteigend) - Default pro Endpoint dokumentiert
Field-Selection (Sparse Fieldsets):
- Query-Param
fields(z.B.?fields=id,first_name,last_name,emails) - Reduziert Payload bei großen Listen
Embed Relations:
- Query-Param
embed(z.B.?embed=primary_company,assigned_to) - Default: nur IDs der Verknüpfungen
- Mit Embed: vollständige Sub-Objekte
- Tiefe max. 1 (kein verschachteltes Embedding in Phase 1)
Response-Format
Erfolg:
{
"data": { ... } oder [...],
"meta": {
"next_cursor": "...",
"total_count_estimate": 1234
}
}
Fehler:
{
"error": {
"code": "validation_failed",
"message": "Klartext-Fehler-Beschreibung",
"details": { "field": "explanation" }
}
}
Endpoint-Details (Beispiel: GET /api/v1/contacts)
Filter:
tag(Multi)assignee_idlead_sourceis_endkundelanguagecreated_at_gte,created_at_lte,updated_at_gte,updated_at_lteq(Volltext über Name/Email/Phone/Notes)archived(Boolean — Default false)custom.{field_key}(für Custom-Felder, dynamisch validiert)
Sortierung:
last_name,first_name,created_at,updated_at,last_activity_at- Default:
-last_activity_at
Embed-Optionen:
primary_company,assigned_to,tags,emails,phones,custom_fields
Sensible Felder (nur mit read_full-Scope):
notescustom_fieldsmitis_sensitive=true(z.B. HR-Personalnummer in Phase 2)- Activities
Endpoint-Details (Beispiel: GET /api/v1/deals)
Filter: pipeline_id, stage_id, assignee_id, tag, value_gte, value_lte, state (open|won|lost), contact_id, company_id, created_at_*, updated_at_*
Sortierung: created_at, updated_at, value, expected_close_date, last_activity_at — Default: -last_activity_at
Embed: pipeline, stage, primary_contact, primary_company, assigned_to, tags
Permissions-aware-Default (AV #5)
- Endpoints filtern automatisch nach Scope
- Sensible Felder werden bei
read_onlyaus Response entfernt (nicht 403, sondern Feld-Auslassung mit Hinweis im OpenAPI-Schema)
Block D — Eingehende Webhooks (Lead-Push)
Endpoint
POST /api/v1/webhooks/incoming/{tenant_slug}/{webhook_slug}
Webhook-Slug-Verwaltung
Verwaltung in /{tenant}/admin/api-keys/incoming-webhooks/ (gemeinsam mit API-Keys aus M27).
Felder pro Slug:
slug(Tenant-eindeutig, z.B.website-kontaktformular)purpose(Enum:lead | form_submission | generic_event— Phase 1: meistlead)auth_method(Enum:api_key | hmac_signature | url_token)secret_or_token_encryptedpayload_mapping(JSONB — Mapping von Webhook-Field zu HiveGrid-Field)default_assignee_id(FK, optional)default_tags[]auto_promote_to_contact(Boolean — sofort als Contact statt Lead anlegen, Default false)is_active,archived_at
Standard-Payload-Format (Lead-Push)
Tenant kann eigenes Mapping definieren, aber Default-Schema für direkten POST:
{
"first_name": "Max",
"last_name": "Mustermann",
"email": "max@example.de",
"phone": "+491234567890",
"message": "Anfrage zur Wartung",
"source_label": "Website-Form",
"metadata": { ...beliebige Felder... }
}
Verarbeitung
- Auth verifizieren (Methode aus Slug-Config)
- Rate-Limit prüfen (siehe Block H)
- Payload validieren (gegen
payload_mapping) IncomingWebhookIngestionmitprocessing_status=processinganlegen- Lead anlegen (Modul 2) mit Mapped-Werten + Source = Slug
- Auto-Match-Versuch: existiert Contact mit selber Email? → falls ja, Activity am Contact statt neuem Lead (oder konfigurierbar pro Slug)
- Auto-Tag aus
default_tags processing_status=done,derived_lead_idgesetzt- Response:
201 Createdmit{ "id": "...", "kind": "lead" }
Fehler-Pfade
- Ungültiges Payload:
400 Bad Requestmit Klartext-Validation-Errors - Auth-Fehler:
401 Unauthorizedmit Klartext - Slug nicht gefunden / inactive:
404 Not Found - Rate-Limit:
429 - Tenant in
frozen-Status:403 Forbiddenmit Klartext: „Workspace ist pausiert — eingehende Webhooks werden aktuell verworfen." - Server-Fehler:
500+ Eintrag inIncomingWebhookIngestion.processing_status=failedfür Debugging
Klartext-Hinweise im Tenant-UI
- Slug-Detail-View zeigt: letzte 100 Ingestion-Events mit Status, Fehler-Klartext, Replay-Button (Phase 2)
- „Webhook-Slug
website-formhat in den letzten 24h: 47 Erfolge, 2 Fehler. [Logs anzeigen]"
Block E — Ausgehende Webhooks
Subscription-Verwaltung in /{tenant}/admin/webhooks/
Felder pro Subscription:
name(interner Name)target_urlsecret(HMAC-Sign — System-generiert, einmalig sichtbar bei Anlage)event_types[](Multi-Select aus verfügbaren Events)filter_definition(optional)
Verfügbare Event-Types (Phase 1)
contact.created
contact.updated
contact.archived
contact.deleted
contact.tag_added
contact.tag_removed
company.created
company.updated
company.archived
lead.created
lead.qualified
lead.converted
lead.lost
lead.spam
deal.created
deal.stage_changed
deal.won
deal.lost
deal.archived
project.created
project.stage_changed
project.completed
project.archived
task.created
task.completed
task.assigned
email.received
email.sent
email.bounced
call.completed
call.missed
Event-Payload-Format
{
"event_id": "evt_...", // unique pro Event-Auslösung, für Idempotenz
"event_type": "contact.created",
"tenant_id": "...",
"tenant_slug": "geerkens",
"occurred_at": "2026-05-08T10:23:00Z",
"data": { /* vollständiges Entity-Objekt analog zu GET /api/v1/<entity>/:id */ },
"previous_data": { /* nur bei *.updated/*_changed — vorheriger Zustand */ }
}
Signatur
- Header
X-HiveGrid-Signature: sha256=<hex>mit HMAC-SHA256(secret, body) - Header
X-HiveGrid-Event: contact.created - Header
X-HiveGrid-Event-Id: evt_...(für Idempotenz) - Empfänger soll Signatur verifizieren + bei Idempotenz-Konflikt 200 OK ohne Re-Processing antworten
Retry-Strategie
- Bei Response 2xx:
delivered - Bei 4xx (außer 408/429):
failed, kein Retry — Klartext: „Endpoint hat 4xx geantwortet — möglicherweise falsch konfiguriert. Subscription bleibt aktiv." - Bei 5xx, 408, 429, Network/Timeout: Retry mit exponentiellem Backoff (1min, 5min, 30min, 2h, 12h) — max. 5 Versuche
- Nach 5 Versuchen:
exhausted,failure_count_consecutiveinkrementiert - Bei
failure_count_consecutive >= 10: Subscription auto-deaktiviert (is_active=false) mit Klartext-Notification: „Webhook ‚[Name]' wurde nach 10 fehlgeschlagenen Auslieferungen deaktiviert. [Reaktivieren]"
Delivery-Stats in Subscription-Detail-View
- Letzte 100 Deliveries mit Status, Response-Code, Response-Excerpt
- Aggregat: „Letzte 7 Tage: 234 Deliveries, 230 erfolgreich (98.3%)"
- Replay-Button pro fehlgeschlagener Delivery (manueller Re-Versuch)
- Test-Funktion: „Test-Event senden" — sendet Sample-Payload mit
event_type=test.ping
Permission
- Subscription-Verwaltung:
tenant.adminODERintegrations.admin - Auslösung: System-Actor
Block F — Allgemeine Event-Ingestion
Endpoint
POST /api/v1/integrations/events
Generischer Ingest für externe Systeme, die Custom-Events pushen wollen (z.B. eigenes ERP pushed Status-Update).
Auth
- API-Key mit Scope
automation_trigger(oderwebhook_inbound)
Payload
{
"event_type": "external.deal_status_changed",
"external_id": "deal-12345",
"data": { ... }
}
Verarbeitung
- Event landet in Automation-Engine (M17) als Trigger
external_event - Event-Filter pro Automation:
event_typeMatch - Phase 1: nur als Trigger (keine direkte Datenmanipulation)
- Phase 2: Event-Mapping zu CRM-Updates
Block G — OpenAPI-Doku
Auto-Generierung
- OpenAPI-3.1-Spec generiert aus Code (Zod-Schemas oder ähnlich)
- Endpoint:
/api/v1/openapi.json - Includiert: alle Endpoints, Request-/Response-Schemas, Auth-Methoden, Beispiele
Swagger-UI
- Endpoint:
/swagger - Öffentlich zugänglich (nicht Tenant-spezifisch)
- „Try it out"-Funktion mit API-Key-Eingabe-Feld
- Beispiel-Requests für alle Endpoints
Klartext-Beschreibungen
- Jeder Endpoint hat Klartext-Description in OpenAPI
- Field-Level-Descriptions für nicht-offensichtliche Felder
- Pflicht-Felder vs. Optional klar markiert
Tenant-spezifische Doku-Hinweise
- In
/{tenant}/admin/api-keys/Verlinkung zu Swagger mit Hinweis: „Verwende deinen API-Key oben rechts in Swagger zum Testen"
Block H — Rate-Limiting
Limits (Phase 1)
- Default pro API-Key: 1.000 Requests/Stunde (rolling)
- Burst: kurzfristig 50 Requests/Sekunde tolerabel
- Pro Tenant aggregiert: 10.000 Requests/Stunde
- Eingehende Webhooks pro Slug: 100 Requests/Minute
- Tenant-Admin kann Limit pro Key erhöhen (max. 10.000/h ohne Plattform-Admin-Approval)
Implementation
- Token-Bucket-Algorithmus
- Counter in Redis pro Key + pro Tenant
- Headers in jeder Response:
X-RateLimit-Limit: 1000X-RateLimit-Remaining: 873X-RateLimit-Reset: 1715169600(Unix-Timestamp)
- Bei Überschreitung: 429 +
Retry-After-Header
Klartext-429-Body
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate-Limit erreicht: 1.000 Anfragen/Stunde. Limit setzt sich um [timestamp] zurück.",
"details": {
"limit": 1000,
"remaining": 0,
"reset_at": "2026-05-08T11:00:00Z",
"tenant_admin_can_increase": true
}
}
}
Metering für Phase 2
- Aggregat-Stats in
/{tenant}/admin/api-keys/{id}/usage/: Tagesverbrauch, Top-Endpoints, Fehler-Rate - Phase 2: Pricing-relevante Über-Limits (Cloud+ erlaubt mehr Requests)
Block I — Versionierung & Stabilität
URL-basierte Versionierung
- Aktuelle Version:
v1 - Pfad:
/api/v1/... - Major-Bump (v2) nur bei Breaking Changes
Backwards-Compatibility-Regeln (Phase 1)
- Neue Felder hinzufügen: erlaubt
- Felder entfernen: nur mit Deprecation-Phase + neuer Version
- Field-Type ändern: nur mit neuer Version
- Pflicht-Filter hinzufügen: nur mit neuer Version
Deprecation-Header
- Endpoints im Sunset-Pfad senden
Sunset: <date>undDeprecation: trueHeader - Klartext-Hinweis in OpenAPI-Description
Stability-Tags pro Endpoint
stable(Phase 1: alle Read-Endpoints)experimental(Phase 2-Vorboten — Kein SLA)deprecated(Sunset angekündigt)
Block J — Permissions / Scope-Mapping
Scope-Mapping zu Endpoints
| Endpoint | Min. Scope |
|---|---|
GET /api/v1/contacts* |
read_only (sensible Felder ausgeblendet) oder read_full |
GET /api/v1/companies* |
read_only oder read_full |
GET /api/v1/deals* |
read_only oder read_full |
GET /api/v1/projects* |
read_only oder read_full |
GET /api/v1/tasks* |
read_only oder read_full |
GET /api/v1/leads* |
read_only oder read_full |
POST /api/v1/webhooks/incoming/* |
webhook_inbound |
POST /api/v1/integrations/events |
automation_trigger |
GET /api/v1/openapi.json |
unauth |
/swagger |
unauth |
Sensible Felder bei read_only
Werden in Response weggelassen (nicht 403, da Endpoint selbst erlaubt ist):
Contact.notesContact.custom_fields[where is_sensitive=true]Deal.notesProject.notesLead.message
Tenant-Status-Wirkung
- Tenant
frozen/past_due(read-only): GET erlaubt, alle POST/PUT/DELETE → 403 mit Klartext: „Workspace ist im Read-Only-Modus." - Tenant
suspended/deleted: alle Requests → 403 / 410 - Tenant
deletion_pending: GET erlaubt, POST/PUT/DELETE blockiert
API-Key-Owner-Wirkung
- API-Keys gehören Tenants, nicht Usern (M27)
- Bei Anfrage werden RLS-Policies mit
app.tenant_id = key.tenant_idgesetzt - Kein User-Owner-Check (Keys sehen alle Tenant-Daten ihres Scopes)
Activity-Stream-Integration
Activity-Typen die M34 produziert (Audit)
api_key_used(nicht pro Request, sondern bei sicherheitsrelevanten Aktionen — Phase 2)webhook_subscription_createdwebhook_subscription_disabled(auto bei Failure-Threshold)incoming_webhook_received(nur fürprocessing_status=donemitderived_lead_id→ Activity am Lead)
Verknüpfungen
- Eingehende Webhooks die Leads erzeugen: Activity am Lead mit
summary_text: „Lead erzeugt aus Webhook ‚[Slug]' am [Datum]"
Permission-Wirkung
- Webhook-Subscription-Audits sichtbar mit
audit.read - API-Request-Logs sichtbar mit
tenant.adminoderintegrations.admin(in/{tenant}/admin/api-keys/{id}/logs/)
Klartext-Hinweise/-Fehler (Querschnitt)
Auth-Fehler
- 401 fehlender Header: „API-Key fehlt. Setze Header:
Authorization: Bearer hg_<dein_key>" - 401 ungültiger Key: „API-Key ist ungültig oder widerrufen."
- 403 falscher Scope: „Dieser API-Key hat Scope
[X], benötigt wird[Y]. Tenant-Admin kann Scope ändern."
Webhook-Fehler
- Eingehender Webhook mit ungültigem Payload: „Pflichtfeld
emailfehlt im Payload. Erwartetes Schema: [Link zur Mapping-Doku]" - Ausgehender Webhook deaktiviert: „Webhook ‚[Name]' ist nach 10 fehlgeschlagenen Auslieferungen deaktiviert. Letzter Fehler: HTTP 502 vom Endpoint. [Reaktivieren]"
Rate-Limit
- „Rate-Limit erreicht. Reset um [Zeit]. Tenant-Admin kann Limit erhöhen unter /admin/api-keys/."
Validation
- „Filter
created_at_gtemuss ISO-8601 sein, z.B.2026-01-01oder2026-01-01T00:00:00Z. Erhalten:[wert]."
Phase 2 / spätere Features
- Voll-CRUD-API: POST/PUT/PATCH/DELETE für alle Hauptentitäten
- GraphQL-Endpoint als zweite Schnittstelle (
/api/graphql) - OAuth2-Provider-Modus: Drittanbieter-Apps können HiveGrid-Daten im Namen des Users abfragen (3-Legged-OAuth)
- Granulare Scopes pro Modul-Aktion: z.B.
contacts:read,contacts:write,deals:read_all - API-Versioning v2 mit Deprecation-Plan für v1
- Webhook-Replay-Tool in UI (für
IncomingWebhookIngestionundWebhookDelivery) - Bulk-Export-Endpoint (
POST /api/v1/exports→ asynchroner Job → S3-Pre-Signed-URL) - Filter-Engine als URL-Param (komplexere Filter-Trees per
?filter=...mit JSON) - Rate-Limit-Tier-Boost über Pricing-Plan (Cloud+ = 5.000/h)
- API-Key-Rotation-Workflow (Übergangsfenster mit zwei aktiven Keys)
- Plattform-Admin-API (
admin.hivegrid.de/api/admin/...) für Tenant-Management
Architektur-Vorschriften (Querschnitt)
- LP-6 Anti-Agentur: API soll für Noah und „dummen Handwerker" pflegbar sein → klare Klartext-Fehler, Swagger-UI mit Try-it-out
- LP-9: Requirements-pur, kein Layout
- LP-10: Klartext-Diagnose bei jedem 4xx/5xx
- LP-11: Webhook-Subscriptions sind selbst Adapter-konform — externe Tools können sich anschließen ohne Code-Änderung in HiveGrid
- LP-13: API-Endpoints laufen auf EU-Servern, Logs in EU-DB
- AV #5 Permissions-aware-Default: Sensible Felder werden bei
read_onlyautomatisch weggelassen - AV #6 Audit-Trail: API-Key-Anlage, Webhook-Setup, alle Lead-Inbound-Events geloggt
Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 34. Phase-1-Basic, bewusst Read-only + Webhooks. Vor Bau: OpenAPI-Tooling-Auswahl (Zod-zu-OpenAPI vs. tRPC-OpenAPI vs. manuell), Rate-Limiter-Implementierung mit Redis testen, HMAC-Signatur-Format dokumentieren.
Offene Detail-Punkte (nicht-blockierend):
- Konkrete Field-Mapping-DSL für Incoming-Webhooks (Phase 1 möglicherweise nur 1:1, Phase 2 mit Transform-Functions)
- Konkretes Default-Tenant-API-Aggregat-Limit (10.000/h vorgeschlagen — final mit Performance-Tests)
- OpenAPI-Hosting-URL (eigene Subdomain
developers.hivegrid.devs./swaggerauf app-Domain) - Subframe-UI-Designs für API-Key-Verwaltung und Webhook-Subscription-View (separat — kommt aus M27)
- Verknüpfung mit Modul 17 Automation-Engine für
external_event-Trigger-Pfad