Events

The events endpoint ingests telemetry from SDKs. Events are batched by the SDK and sent as an array. This endpoint uses public key authentication.

Ingest Events

POST /v1/events/:public_key

This endpoint authenticates via the public key in the URL path, not via the Authorization header. This allows SDKs to post events without exposing the private key.

Request Body

Field	Type	Required	Description
`events`	array	Yes	Array of event objects (min 1)

Event Object

Field	Type	Required	Description
`event_name`	string	Yes	Event name (see standard events below)
`timestamp`	string	Yes	ISO 8601 timestamp
`device_id`	string	No	Device identifier
`user_id`	string	No	User identifier (set via `identify()`)
`properties`	object	No	Arbitrary key-value properties
`campaign_id`	string	No	Associated campaign ID
`paywall_id`	string	No	Associated paywall ID

Example

curl -X POST https://agentwallie.com/api/v1/events/pk_your_public_key \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "paywall_open",
        "timestamp": "2025-03-15T10:30:00.000Z",
        "device_id": "device_abc123",
        "user_id": "user_456",
        "campaign_id": "camp_abc123",
        "paywall_id": "pw_def456",
        "properties": {
          "placement": "onboarding_complete",
          "platform": "ios",
          "app_version": "2.1.0"
        }
      },
      {
        "event_name": "purchase_started",
        "timestamp": "2025-03-15T10:30:15.000Z",
        "device_id": "device_abc123",
        "user_id": "user_456",
        "campaign_id": "camp_abc123",
        "paywall_id": "pw_def456",
        "properties": {
          "slot": "primary",
          "store_product_id": "com.app.annual"
        }
      }
    ]
  }'

Response `201 Created`

{
  "ingested": 2
}

Standard Event Names

These events are tracked automatically by the SDKs:

Event Name	Description
`placement_triggered`	SDK evaluated a placement
`paywall_open`	Paywall was presented to the user
`paywall_close`	Paywall was dismissed
`purchase_started`	User initiated a purchase
`transaction_complete`	Purchase completed successfully
`transaction_fail`	Purchase failed
`restore_started`	User initiated a restore
`restore_complete`	Restore completed

Custom events can use any name. Track them via AgentWallie.shared.trackEvent(name:properties:) in the SDK.

Side Effects

When events are ingested, two background processes run asynchronously:

Webhook dispatch: If any webhooks are configured for the ingested event names, they are dispatched with the event data.
Auto-promote check: If any ingested events reference paywalls that are part of an active experiment with auto_promote enabled, the system checks if the experiment has reached statistical significance and promotes the winner if so.

Batch Ingestion

The SDK batches events and sends them periodically (typically every 30 seconds or when the app backgrounds). You can also batch events manually from a server-side integration.

⚠️

The events endpoint is rate-limited to 120 requests per minute per IP. Each request can contain multiple events, so batch them for efficiency.

Analytics SDK Config