Server API

curl -sS https://apis.kentro.live/pixel/v1/properties/$PROPERTY_ID/server-keys \
  -H "Authorization: Bearer $KENTRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "orders backend" }'

{
  "server_key": {
    "id": "0192f0c7-3c4d-7e5f-9061-7b8c9d0e1f2a",
    "key_id": "sk_4fHq8Lm2Tz9Wb1Xc",
    "label": "orders backend",
    "status": "active",
    "last_used_at": null,
    "created_at": "2026-10-09T17:30:00.000Z",
    "revoked_at": null,
    "secret": "kQ9vX2mT7pL4wR8zN1cB6yH3jF5dS0aG2eU7iO9qW4E"
  }
}

KEY_ID='sk_4fHq8Lm2Tz9Wb1Xc'
SECRET='kQ9vX2mT7pL4wR8zN1cB6yH3jF5dS0aG2eU7iO9qW4E'
BODY='{"events":[{"event_id":"order-1001-paid","event_name":"commerce.order_paid","order_ref":"order-1001","commerce_subject_ref":"cust-42","properties":{"order_id":"order-1001","total":{"amount_minor":4999,"currency":"USD"},"payment_method":"card"}}]}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"

curl -sS https://pixel.kentro.live/v1/server/events \
  -H "Content-Type: application/json" \
  -H "X-Kentro-Key-Id: $KEY_ID" \
  -H "X-Kentro-Timestamp: $TS" \
  -H "X-Kentro-Signature: $SIG" \
  -H "X-Kentro-Idempotency-Key: order-1001-paid" \
  --data-binary "$BODY"

const crypto = require('node:crypto');

const KEY_ID = process.env.KENTRO_PIXEL_KEY_ID;     // sk_...
const SECRET = process.env.KENTRO_PIXEL_KEY_SECRET; // shown once when the key was created

async function sendServerEvents(events, idempotencyKey) {
  const body = JSON.stringify({ events });
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signature = 'sha256=' + crypto.createHmac('sha256', SECRET).update(`${timestamp}.${body}`).digest('hex');

  const res = await fetch('https://pixel.kentro.live/v1/server/events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Kentro-Key-Id': KEY_ID,
      'X-Kentro-Timestamp': timestamp,
      'X-Kentro-Signature': signature,
      ...(idempotencyKey ? { 'X-Kentro-Idempotency-Key': idempotencyKey } : {}),
    },
    body,
  });
  const result = await res.json();
  if (res.status !== 202) throw new Error(`Kentro Pixel ${res.status}: ${result.error}`);
  return result; // { receipt_id, results: [{ event_id, status, reason_code? }] }
}

sendServerEvents([
  {
    event_id: 'order-1001-paid',
    event_name: 'commerce.order_paid',
    occurred_at: new Date().toISOString(),
    order_ref: 'order-1001',
    commerce_subject_ref: 'cust-42',
    properties: {
      order_id: 'order-1001',
      total: { amount_minor: 4999, currency: 'USD' },
      payment_method: 'card',
    },
  },
], 'order-1001-paid').then((receipt) => console.log(receipt.results));

import hashlib
import hmac
import json
import os
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone

KEY_ID = os.environ["KENTRO_PIXEL_KEY_ID"]      # sk_...
SECRET = os.environ["KENTRO_PIXEL_KEY_SECRET"]  # shown once when the key was created


def send_server_events(events, idempotency_key=None):
    body = json.dumps({"events": events}, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    digest = hmac.new(SECRET.encode("utf-8"), timestamp.encode("ascii") + b"." + body, hashlib.sha256).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-Kentro-Key-Id": KEY_ID,
        "X-Kentro-Timestamp": timestamp,
        "X-Kentro-Signature": "sha256=" + digest,
    }
    if idempotency_key:
        headers["X-Kentro-Idempotency-Key"] = idempotency_key
    request = urllib.request.Request("https://pixel.kentro.live/v1/server/events", data=body, headers=headers, method="POST")
    try:
        with urllib.request.urlopen(request, timeout=10) as response:
            return json.load(response)  # {"receipt_id": ..., "results": [...]}
    except urllib.error.HTTPError as error:
        raise RuntimeError(f"Kentro Pixel {error.code}: {error.read().decode()}") from error


receipt = send_server_events([{
    "event_id": "order-1001-paid",
    "event_name": "commerce.order_paid",
    "occurred_at": datetime.now(timezone.utc).isoformat(),
    "order_ref": "order-1001",
    "commerce_subject_ref": "cust-42",
    "properties": {
        "order_id": "order-1001",
        "total": {"amount_minor": 4999, "currency": "USD"},
        "payment_method": "card",
    },
}], idempotency_key="order-1001-paid")
print(receipt["results"])

kentroPixel('track', 'commerce.checkout_started', { checkout_id: 'chk-1001' }, { event_id: 'chk-1001-started' });

{
  "receipt_id": "0192f0c8-0b1c-7d2e-9f30-4a5b6c7d8e9f",
  "results": [
    { "event_id": "order-1001-paid", "status": "accepted" }
  ]
}

You are sending server-side events from the user's backend to Kentro Pixel: authoritative facts such as commerce.order_paid and refunds. Revenue reporting trusts these facts only when they come from a server source.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/docs/kentro-pixel.md
- https://docs.kentro.io/docs/pixel-server-api.md
- https://docs.kentro.io/docs/pixel-events.md
- https://docs.kentro.io/docs/pixel-consent-privacy.md

Ask the user for these before writing code:
1. The backend language and framework, and where payment success and refunds are recorded.
2. A server key for the Pixel property, created in Kentro GO on the property's `Keys` tab (or with POST https://apis.kentro.live/pixel/v1/properties/:id/server-keys). The secret is shown once. Ask the user to store the key id (sk_...) as KENTRO_PIXEL_KEY_ID and the secret as KENTRO_PIXEL_SECRET in the environment, never in the chat or the browser.
3. The collector: https://pixel.kentro.live for production or https://pixel.kentro.dev for Kentro staging.
4. Which business events to send, mapped to event names from the Events page.

Rules:
- POST each batch to `<collector>/v1/server/events` with Content-Type: application/json and three headers: X-Kentro-Key-Id with the key id; X-Kentro-Timestamp with the current Unix time in seconds; X-Kentro-Signature with sha256= followed by the hex HMAC-SHA256 of `"<timestamp>.<raw body>"` keyed with the secret. Sign the exact bytes you send: serialize the body once.
- The timestamp must be within 300 seconds of Kentro's clock, or the request is refused with TIMESTAMP_STALE. A wrong signature is refused with SIGNATURE_INVALID.
- Give every event a stable event_id derived from the business fact (for example the order id plus the event name), so a retry is deduplicated. Kentro deduplicates event ids for at least 14 days. Never generate a new id for a retry.
- event_name is lowercase and dotted (commerce.order_paid). occurred_at is ISO-8601, no more than 7 days in the past or 5 minutes in the future. Each event stays under 32 KB.
- Money follows the event schema in integer minor units; floating-point money is rejected. Read the schemas from GET https://apis.kentro.live/pixel/v1/event-schemas and check events with POST /v1/event-schemas/validate before sending.
- Send consent and identity fields as the Server API and consent pages describe, and never send personal data the schema does not ask for.
- Send after the database commit, from a queue or outbox, so a crash neither loses nor double-sends an event. Retry network errors, 429 and 5xx with backoff and the same event_id.

Steps:
1. A signer module, with a unit test against a fixed timestamp, body and secret.
2. A sender that batches events, posts them, and logs the receipt_id and each event's status.
3. Hooks on payment success and refunds that enqueue the events.
4. A dead-letter path for events that keep failing, with their reason codes.

Acceptance checks. Run each one against Kentro staging or a test property and show the user the requests and responses, with secrets redacted:
- One signed commerce.order_paid event answers 202 with results[0].status accepted.
- The same event sent again answers status duplicate and creates no second record.
- A request whose timestamp is 10 minutes old is refused with TIMESTAMP_STALE, and one with a wrong signature with SIGNATURE_INVALID.
- The event appears in the property's `Debugger` tab with source_type server.
- No server secret appears in code, logs or client assets.