# Public Lead Intake — eingehender Webhook Öffentlicher Endpunkt, über den externe Systeme (Website-Kontaktformular, Landingpage, Zapier/Make, Partner-CRM …) einen **Lead** direkt in einen HiveGrid-Tenant einliefern. Aus dem eingelieferten JSON wird ein `InboxLead` im Ziel-Tenant erzeugt, gegen bestehende Kontakte gematcht und optional als `webhook.received`-Trigger für Automationen ausgewertet. - **Route:** `POST /v1/webhooks/incoming/:tenant/:slug` - **Implementierung:** Route `apps/api/src/routes/public-api-routes.ts` (`postPublicIncomingWebhookRequest`) → Service `ingestPublicLeadWebhook` in `packages/db/src/public-api.server.ts` - **Content-Type:** `application/json` (Body muss ein JSON-**Objekt** sein, kein Array/Skalar) ## Adressierung: `:tenant` und `:slug` - `:tenant` — Tenant-**ID** oder Tenant-**Slug** (beides wird aufgelöst). - `:slug` — Slug des Webhook-Endpunkts (`PublicIncomingWebhookEndpoint`), pro Tenant eindeutig. Der Endpunkt muss `status = "active"` sein. Unbekannter Tenant, unbekannter Slug **oder** inaktiver Endpunkt liefern einheitlich `404 not_found` — bewusst ohne Unterscheidung, damit von außen nicht erkennbar ist, ob Tenant oder Slug falsch war (keine Enumeration). ## Authentifizierung — drei Modi Der Auth-Modus ist **pro Endpunkt** konfiguriert (`authMode`). Es gilt genau der Modus des adressierten Endpunkts; ein anderer Modus wird nicht akzeptiert. ### 1. `api_key` - Header **`x-api-key: `** (alternativ Feld `apiKey` im JSON-Body). - Der Schlüssel muss zum **selben Tenant** gehören wie der Endpunkt; ist am Endpunkt ein `apiKeyId` hinterlegt, muss es **genau dieser** Schlüssel sein. - Der Schlüssel muss `active` und nicht abgelaufen sein und den Scope **`public_api:webhooks:incoming`** (oder `*`) besitzen. Fehlt der Scope → `403 insufficient_scope`. ### 2. `url_token` - Header **`X-HiveGrid-Webhook-Token: `** — alternativ Query-Parameter **`?token=`** (praktisch für Formular-Tools, die keine Custom-Header senden können). - Das Token wird gegen den gespeicherten `tokenHash` geprüft (der Klartext wird nie gespeichert und ist nur einmal bei der Erstellung sichtbar). ### 3. `hmac` - Header **`X-HiveGrid-Webhook-Token: `** (das einmalig ausgegebene Secret), **`X-HiveGrid-Timestamp: `** und **`X-HiveGrid-Signature: sha256=`**. - Signatur = `HMAC-SHA256(secret, ".")`, hex-kodiert, mit Präfix `sha256=`. Signiert wird der **rohe** Request-Body (Byte-für-Byte), nicht das neu serialisierte JSON. Ungültige Credentials in jedem Modus → `401 unauthorized` (ohne Detail, welcher Teil falsch war). ## Rate-Limit Fixed-Window-Limiter (Fenster: **1 Stunde**), zwei Ebenen gleichzeitig: | Ebene | Limit / Stunde | Zähl-Schlüssel | |---|---|---| | pro Schlüssel/Endpunkt | **1.000** | API-Key-ID (`api_key`) bzw. Endpunkt-ID (`url_token`/`hmac`) | | pro Tenant | **10.000** | Tenant-ID | Bei **jeder** Antwort (Erfolg wie Ablehnung) werden Rate-Limit-Header gesetzt: | Header | Bedeutung | |---|---| | `X-RateLimit-Limit` | geltendes Limit (bei kombinierter Sicht `1000`) | | `X-RateLimit-Remaining` | verbleibende Anfragen im Fenster (Minimum beider Ebenen) | | `X-RateLimit-Reset` | Unix-Zeit (Sekunden), wann das Fenster zurücksetzt | | `X-RateLimit-Scope` | `key`, `tenant` oder `combined` (welche Ebene griff) | Bei Überschreitung → `429 rate_limit_exceeded`, zusätzlich `Retry-After` (Sekunden bis Reset). ## Feld-Mapping (`payloadMapping`) Aus dem JSON-Body werden fünf strukturierte Lead-Felder extrahiert. Für jedes Feld gibt es Standard-Pfade; über `payloadMapping` (JSON am Endpunkt) lässt sich pro Feld ein abweichender **Dot-Pfad** in den Payload setzen. | Lead-Feld | Standard-Pfade (in Reihenfolge) | |---|---| | `vorname` | `vorname`, `firstName`, `first_name`, `contact.firstName` | | `nachname` | `nachname`, `lastName`, `last_name`, `contact.lastName` | | `email` | `email`, `contact.email`, `from.email` (wird auf lowercase normalisiert) | | `telefon` | `telefon`, `phone`, `telephone`, `contact.phone` | | `message` | `message`, `nachricht`, `text`, `body` | - `payloadMapping`-Beispiel: `{ "email": "customer.mail", "message": "form.comment" }` liest `email` aus `customer.mail` und `message` aus `form.comment`; für nicht gemappte Felder greifen weiter die Standard-Pfade. - Werte werden getrimmt und auf **2.000 Zeichen** gekürzt. - Der **komplette** eingelieferte Payload wird zusätzlich unverändert in `rohdaten` gespeichert — Felder wie **Firma**, **Quelle/Kampagne** oder eigene **Metadaten** gehen also nicht verloren, werden aber (Stand heute) nicht in eigene Lead-Spalten gemappt (siehe „Bekannte Grenzen"). ### Kontakt-Matching Nach der Extraktion wird versucht, den Lead einem bestehenden Kontakt zuzuordnen: zuerst per **E-Mail** (`KontaktEmail`), sonst per **Telefon** (`KontaktTelefon`), jeweils tenant-scoped. Treffer landet als `matchedKontaktId` am Lead und in der Antwort. ## Beispiel — Demo-Endpunkt Demo-Tenant `hivegrid-demo`, Endpunkt-Slug `website-kontaktformular` (`authMode: "api_key"`, verknüpft mit dem API-Key-Alias „Website Lead Intake"). Den echten Schlüssel im Tenant-Dashboard erzeugen/ablesen; unten steht ein Platzhalter, **kein echtes Secret**. ```bash curl -sS -X POST \ "https://api.hivegrid.de/v1/webhooks/incoming/hivegrid-demo/website-kontaktformular" \ -H "content-type: application/json" \ -H "x-api-key: $HIVEGRID_API_KEY" \ -d '{ "firstName": "Ada", "lastName": "Lovelace", "company": "Analytical Engines GmbH", "email": "ada@example.test", "phone": "+49 30 1234567", "message": "Bitte um ein Angebot für eine 12-kWp-Anlage.", "source": "website", "campaign": "sommer-2026", "meta": { "utm_medium": "cpc", "formId": "kontakt-hero" } }' ``` - Bei `authMode: "url_token"` stattdessen `-H "x-hivegrid-webhook-token: $TOKEN"` (oder `?token=$TOKEN` an die URL). - Der API-Key muss den Scope `public_api:webhooks:incoming` besitzen (der reine Lese-/Schreib-Scope reicht **nicht**). ### Erfolgs-Antwort (`201`) ```json { "data": { "leadId": "clx…", "matchedKontaktId": null, "automationExecutionIds": [] }, "meta": { "requestId": "req_…", "endpoint": "website-kontaktformular" } } ``` Aus dem Beispiel-Payload werden `vorname=Ada`, `nachname=Lovelace`, `email=ada@example.test`, `telefon=+49 30 1234567`, `message=…` gesetzt; `company`, `source`, `campaign`, `meta` bleiben in `rohdaten` erhalten. ## Fehlerverhalten Alle Fehler nutzen die Standard-Hülle `{ "error": { "code", "message", "requestId" } }` (Details bewusst knapp, keine Stacktraces, keine Secrets, keine internen IDs im Klartext). | Status | `code` | Auslöser | |---|---|---| | `404` | `not_found` | Tenant/Slug unbekannt oder Endpunkt inaktiv | | `400` | `invalid_json` | Body ist kein JSON-Objekt / nicht parsebar | | `401` | `unauthorized` | fehlendes/ungültiges Token, HMAC oder API-Key | | `403` | `insufficient_scope` | API-Key ohne `public_api:webhooks:incoming` | | `402` | `payment_required` | Tenant read-only (Billing) oder API-Zugang aus/aufgebraucht | | `429` | `rate_limit_exceeded` | Rate-Limit überschritten (mit `Retry-After`) | | `500` | `webhook_ingestion_failed` | interner Fehler beim Anlegen | ## Was serverseitig passiert 1. Tenant + Endpunkt auflösen, Endpunkt-Status prüfen. 2. Body als JSON-Objekt parsen. 3. Billing-/Usage-Gate (`402` bei read-only oder deaktiviertem API-Zugang). 4. Auth gemäß `authMode` + Rate-Limit. 5. In **einer** Transaktion: Kontakt-Matching, `InboxLead` anlegen, **Audit-Event** für die Lead-Erstellung über die transaktionale Outbox (`audit.event.create`, Action `lead.created`, Target `lead`) — commit-atomar mit dem Lead; die manipulationssichere Hash-Kette wird asynchron vom `audit-event-persist`-Worker verkettet. Anschließend passende `webhook.received`-Automationen einreihen und ein `PublicWebhookIngestionLog` schreiben. ## Bekannte Grenzen (Stand dieser Doku) Der Intake schreibt bewusst **nur** Lead + Audit + Ingestion-Log + Automation-Einreihung. Im Vergleich zum internen Service `leadService.createLead` fehlen (bewusst, als Folgearbeit): - **Anti-Spam-Scoring** (`spamScore`, Quarantäne, Ratenanomalie) — der Public-Intake setzt keinen Spam-Score. - **`lead.created`-Outbox-Fan-out** (Workflow-Engine/Notifications über den Lead-Workflow-Event) — nur die Audit-Outbox wird geschrieben. - **Such-Projektion** (Meilisearch-Upsert des Leads). - **Activity-Stream-Eintrag** (`logActivity`) — siehe Hinweis unten. - **Firma/Quelle/Kampagne** werden nicht in eigene Lead-Felder gemappt (nur in `rohdaten` erhalten). > Der Activity-Eintrag wird hier nicht geschrieben, weil `@hivegrid/activity` > von `@hivegrid/db` abhängt; ein Import in `packages/db` erzeugte einen > Paket-Zyklus. Der saubere Weg ist eine geteilte Lead-Ingestion-Schicht bzw. > ein `logActivity`-Aufruf auf Route-Ebene (`apps/api`, darf `@hivegrid/activity` > importieren) — nachzuziehen, wenn der Intake ohnehin angefasst wird.