Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,210 @@
# 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: <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: <token>`** — alternativ Query-Parameter
**`?token=<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: <secret>`** (das einmalig ausgegebene
Secret), **`X-HiveGrid-Timestamp: <unix-seconds>`** und
**`X-HiveGrid-Signature: sha256=<hex>`**.
- Signatur = `HMAC-SHA256(secret, "<timestamp>.<raw-body>")`, 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.