211 lines
9.0 KiB
Markdown
211 lines
9.0 KiB
Markdown
# 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.
|