Custom Events API

Use the Custom Events API to send backend events to Spindl. Events must be sent as an array to:

POST https://spindl.link/events/server

To send a single event, wrap it in a one-item array.

Create an API key

If you don’t already have an API key, generate one on the Settings page in the Spindl app.

API keys are different from SDK keys. Keep API keys private and never include them in client-side code or publicly accessible repositories. If a key is exposed, revoke it from the Settings page.

Authentication

Pass your API key in the X-API-Key header:


X-API-Key: YOUR_API_KEY
Content-Type: application/json

Request body

The request body is an array of event objects with the following fields:

Field	Required	Description
`type`	Yes	Must be `CUSTOM`.
`data.name`	Yes	Event name between 3 and 100 characters. Alphanumeric characters, spaces, `_`, `:`, and `-` are supported.
`data.properties`	No	Additional event data as a JSON object, up to 16 KB. Keys and values cannot exceed 1,000 characters.
`identity.address`	Conditional	A valid wallet address. At least one identity field is required.
`identity.customerUserId`	Conditional	Your unique user ID, such as a database ID or email address. At least one identity field is required.

Identity fields allow Spindl to associate events with users and provide accurate attribution. You may provide either identity field or both.

Example request


curl --location 'https://spindl.link/events/server' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "type": "CUSTOM",
      "data": {
        "name": "ADD_TO_CART",
        "properties": {
          "productId": "example-product"
        }
      },
      "identity": {
        "address": "0x0000000000000000000000000000000000000000",
        "customerUserId": "user-123"
      }
    }
  ]'

A successful request returns 204 No Content.

JavaScript fetch example


const response = await fetch('https://spindl.link/events/server', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      type: 'CUSTOM',
      data: {
        name: 'ADD_TO_CART',
        properties: {
          productId: 'example-product'
        }
      },
      identity: {
        customerUserId: 'user-123'
      }
    }
  ])
})
 
if (!response.ok) {
  throw new Error(`Spindl API request failed: ${response.status}`)
}