Server-side events

Some things a browser should not be allowed to claim. A payment that settled, a subscription that really cancelled, a trial that actually converted — if a visitor could send it, it is not evidence.

POST /v1/events takes those from your own backend, authenticated with a key scoped to one site.

// Server-side events: things the browser must not be trusted to assert.
await fetch("https://collect.inqetra.com/v1/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.INQETRA_API_KEY}`, // inq_live_xxxxxxxxxxxx
  },
  body: JSON.stringify({
    name: "payment",
    url: "https://example.com/checkout/success",
    visitor: user.id, // hashed at the edge, never stored in the clear
    properties: { plan: "pro", amount: 4900, currency: "usd" },
  }),
});

API keys

Create one under Events in the dashboard. It is scoped to that site, and the plaintext is shown exactly once — only a SHA-256 of it is stored, so there is no screen anywhere that can show it to you again. Lose it and you revoke it and make another.

Revocation takes effect at the edge, not at the next deploy.

The body

• name — required. Same rules as a browser event, and the tracker’s own names are reserved.
• url — the page the event belongs to. Only the path is kept.
• visitor — whatever identifies this person to you, usually your own user id. It is hashed at the edge with the same daily-rotating salt as a browser visitor and never stored in the clear.
• properties — an object of your own values.
• referrer — optional.

What it answers

400

The body was not JSON, the name did not match the pattern, the name is reserved for the tracker, or `url` was not a valid URL.

401

No `Authorization: Bearer` header, or a key that is unknown or has been revoked.

405

Anything other than POST.

429

The rate limit for this key. A `Retry-After` header comes with it.

500

The event could not be recorded. Nothing was written; retry is safe.