Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user