Events tracken

POST /v1/events/track ist ein öffentlicher, ausschließlich schreibender Endpoint, der dafür gebaut ist, direkt von der eigenen Website eines Kunden aufgerufen zu werden — er kann Events entgegennehmen, aber nichts zurücklesen, daher ist der Aufruf mit einem reinen Public Key sicher, anders als bei Ihrem Haupt-API-Key.

Ein einzelnes Event tracken

curl -X POST https://api.wezend.com/v1/events/track \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "wz_pk_...",
    "event": "product_viewed",
    "identifiers": { "email": "anna@example.com" },
    "properties": { "sku": "DK-1180", "price": 499 }
  }'

Ein einzelnes Event gibt 202 { "ok": true } zurück.

Events werden über identifiers (E-Mail oder Telefon) einem Kontaktprofil zugeordnet — ein Event ohne identifiers (oder eine anonymous_id) wird angenommen, kann aber nie mit einem Kontaktprofil verknüpft werden.

Events als Batch

{
  "public_key": "wz_pk_...",
  "events": [
    { "event": "product_viewed", "identifiers": { "email": "anna@example.com" }, "properties": { "sku": "DK-1180" } },
    { "event": "add_to_cart", "identifiers": { "email": "anna@example.com" }, "properties": { "sku": "DK-1180", "qty": 1 } }
  ]
}

gibt 202 { "accepted": 2, "rejected": 0 } zurück.

Origin-Beschränkung

Sie können den Key als X-ZC-Key statt im Body übergeben. Jeder Public Key lässt sich optional auf eine Allowlist von Origins beschränken, sodass ein geleakter Key nur genutzt werden kann, um Events von Ihren eigenen Domains zu senden — eine leere Allowlist bedeutet beliebige Origins. GET /v1/account/tracking-key liefert diesen Key zusammen mit einem fertigen <script>-Snippet, und PUT /v1/account/tracking-origins setzt die Allowlist (z. B. ["https://shop.beispiel.de"]).

Einen benannten Kontakt identifizieren

Event-Tracking benennt niemanden und braucht daher keine Signatur: der Public Key identifiziert Ihr Konto und sonst nichts. Alles, was für einen benannten Kontakt spricht, braucht eine — der In-App-Posteingang (POST /v1/inapp/feed, POST /v1/inapp/read) und das Verknüpfen eines Push-Geräts mit einem Kontakt (POST /v1/push/subscribe mit einer email). Der Public Key steht in Ihrem Seitenquelltext und kann deshalb allein nie belegen, dass die besuchende Person genau einer Ihrer Kontakte ist.

Diese Aufrufe erwarten eine Signatur, die Ihr eigener Server erzeugt — user_hash = HMAC-SHA256(lowercase(trim(email)), Ihr Identity-Secret), hex:

// your backend, when rendering the page — never in browser code
const crypto = require("crypto");
const email = user.email.trim().toLowerCase();
const userHash = crypto.createHmac("sha256", process.env.WEZEND_IDENTITY_SECRET)
                       .update(email).digest("hex");
// hand userHash to the page next to the email, then: wezend.identify(email, userHash)

Setzen Sie die Adresse vor dem Hashen auf Kleinbuchstaben und trimmen Sie sie. Wir tun dasselbe, sodass Anna@Firma.dk und anna@firma.dk als derselbe Kontakt verifizieren — die Suche hinter der Signatur ist ebenfalls case-insensitiv. Signieren Sie den rohen String, erhält jemand, der einen Großbuchstaben getippt hat, einen 403, der wie unser Fehler aussieht.

Das Secret kommt von GET /v1/account/tracking-identity (Dashboard: Einstellungen → Tracking) und ist nicht der Public Key — halten Sie es auf Ihrem Server. POST /v1/account/tracking-identity/rotate stellt ein neues aus und macht jeden bereits berechneten Hash ungültig, also rollen Sie das neue Secret vor der Rotation aus. Ein Aufruf, der eine Signatur braucht und ohne kommt, wird mit 403 und identity_required: true abgewiesen. Die Push-Registrierung kann darauf verzichten, indem sie email weglässt — das Gerät ist dann anonym. Schalten Sie die Anforderung ganz ab (PUT /v1/account/tracking-identity mit { "require_identity": false }), kann jede Person, die Ihren Seitenquelltext liest, die Nachrichten jedes Kontakts abrufen, indem sie dessen Adresse angibt — also nur, wenn Sie keinen identifizierten Traffic haben.

Was danach passiert

Sobald Events eintreffen, werden berechnete Traits neu berechnet und Segmentzugehörigkeiten in Echtzeit aktualisiert — jede Journey, die diesen Trigger oder dieses Segment beobachtet, kann sofort auslösen, ganz ohne Batch-Job.