Server events

1. Prerequisites

Website: installation ID

Open Arenza Portal → AI Integrations, select your brand, and copy Website install ID. It starts with arz_pub_. Replace YOUR_INSTALL_ID below with that value.

Python / Go: create an API Key

1. Open AI Integrations → Personal Access Tokens.
2. Click New token, enter a name such as Server events, and select Write.
3. Click Create token and copy the arn_pat_… value. It is displayed only once.
4. Save it on your backend as ARENZA_API_KEY. Save your Website install ID as ARENZA_INSTALL_ID.

The examples use these environment variable names. Inject the Key from your server's secret manager; never place it in website code. No separate Signing Secret is needed. The receiver checks Authorization: Bearer <API_KEY>, the Key's write permission and access to the brand.

To replace a Key, create another, update your backend, then revoke the old one in the same token list. Revoked Keys stop working on subsequent requests.

Event setup is separate from Key creation. The selected brand must already have a configured server event connection and allowed event_handle. A measurement-only Website install ID returns 422 server_event_not_configured; creating a Key does not create a billing contract or enable arbitrary event types. Ask Arenza to confirm the supported event for that brand if it is not configured.

2. Examples

Python

Use ARENZA_API_KEY and ARENZA_INSTALL_ID from Prerequisites. Supply the event object and a saved delivery UUID. No browser session token is needed.

Copy the HTTP helper into your project as arenza_events.py. Then call it from your event handler:

from arenza_events import send_event

# event: saved event object from Server event fields below.
# delivery_id: your saved delivery UUID (generate once, not on each retry).
receipt = send_event(event, delivery_id)
# Save receipt["receipt_id"] with your delivery record.

Go

Use ARENZA_API_KEY and ARENZA_INSTALL_ID from Prerequisites. Supply the event object and a saved delivery UUID. No browser session token is needed.

Copy the HTTP helper into your Go module's arenza package (Go 1.18+). Import that package in your handler:

// event: saved event map from Server event fields below.
// deliveryID: saved delivery UUID. ctx: your worker's context.
receipt, err := arenza.SendEvent(ctx, event, deliveryID)
if err != nil {
    return err // Let your worker apply its retry/error policy.
}
// Save receipt.ReceiptID with your delivery record.

3. Parameters and responses

When to send

You decide when to execute that snippet:

Current limit: browser track() does not support named event types. These are possible trigger locations, not distinct event names in Arenza reports. track('booking_confirmed') is unsupported. Choose one reporting path per occurrence: SDK, raw HTTP or server webhook.

Visitor ID handoff

After installing the HTML or JavaScript example, read the visitor ID:

JavaScript (browser)

const visitorId = window.arenzaEvents.getVisitorId();

Add that value as arenza_visitor_id to your existing request to your own backend. Your backend should save it with the relevant business record so an asynchronous worker can use it later. The getter sends no event. Do not also call browser track() for the same server-reported event.

Server event fields

Use this endpoint:

POST https://api.arenza.ai/api/v1/billing-events/{website_install_id}

With API Key authentication, the arz_pub_… Website install ID is an alias for your brand's configured connection. Existing connection UUIDs also remain valid; do not put the API Key in the URL.

Required headers: Authorization: Bearer <API_KEY>, Content-Type: application/json, and webhook-id: <delivery UUID>. No HMAC signature or timestamp is required on this path.

In the Arenza request, put that same ID under attribution.visitor_id, not a top-level arenza_visitor_id:

JSON — example test event; replace values with your business record

{
  "spec_version": "1.0",
  "event_id": "booking-event-123",
  "event_handle": "YOUR_CONFIGURED_EVENT_HANDLE",
  "occurred_at": "2026-09-24T12:00:00Z",
  "subject": { "type": "booking", "id": "booking-123" },
  "attribution": { "visitor_id": "arz_v_aaaaaaaaaaaa" },
  "status": "test"
}

Responses and errors

HTML / JavaScript: trigger an approved test once, then check DevTools → Network for one /events request returning 202. This means received, not independent proof of the business outcome.

Python / Go:

A successful request returns 202:

{
  "accepted": true,
  "receipt_id": "<receipt ID>",
  "duplicate": false,
  "status_url": "/api/v1/billing-events/<connection ID>/receipts/<receipt ID>"
}

202 means queued, not that attribution, reporting or billing has completed. Save the receipt for processing checks.

• 401: the API Key is missing, invalid or revoked.
• 403 insufficient_scope: create a Key with Write permission.
• 404: the connection is unavailable or the Key has no access to its brand.
• 422 server_event_not_configured: this installation has no configured server event binding.
• 422 event_handle_not_allowed: the event type is not configured for this connection.
• 409: an event/delivery ID may have been reused with a changed body.
• Network failures or 5xx: retry through your worker using the same IDs and unchanged event; do not generate a new event ID or delivery ID for the retry. Avoid unbounded immediate retries.

Test only against an approved connection. The examples do not send until you call the function.

Existing preconfigured connections

An existing pre-bound integration can accept just {"arenza_visitor_id":"arz_v_…"} at /api/v1/billing-events/{website_install_id}/preconfigured, with the same Bearer, content-type and webhook-id headers. It only supports its preconfigured event binding. Do not use that minimal body on the general endpoint above, and do not assume it supports arbitrary event types.

HTTP / curl reference · JSON Schema · Stopping collection

Existing HMAC-signed integrations continue to work with their connection UUID and signature headers. API Key callers do not need to obtain or rotate those signing secrets.

Production verification: 2026-09-24 — tested paths, deployed version, authentication checks and limits of the evidence.