Sending Events

Learn how to send events to your Eventkiwi aggregator using simple HTTP requests.

Event Basics

Every event sent to Eventkiwi requires two pieces of information:

1. Aggregator ID (_id) - Identifies which aggregator receives the event
2. Event Name (name) - A string identifying the type of event

Events are sent to the /api/event endpoint using either GET or POST requests.

Endpoint

https://app.eventkiwi.com/api/event

Required Parameters

Parameter	Type	Location	Description
_id	string	URL query	Your aggregator ID
_apikey	string	URL query or Header	Your API key (see Authentication)
name	string	URL query or Body	The event name

Using GET Requests

GET requests are the simplest way to send events. All parameters are passed in the URL.

Basic Example

GET https://app.eventkiwi.com/api/event?_id=YOUR_AGGREGATOR_ID&_apikey=YOUR_API_KEY&name=user_signup

With cURL

curl "https://app.eventkiwi.com/api/event?_id=YOUR_AGGREGATOR_ID&_apikey=YOUR_API_KEY&name=user_signup"

tip

For production applications, use environment variables to store credentials and prefer POST requests with Bearer token authentication. See Language Examples for ready-to-use helper functions.

Using POST Requests

POST requests are recommended for production use, especially when using Bearer token authentication or sending tags.

Basic Example

curl -X POST "https://app.eventkiwi.com/api/event?_id=YOUR_AGGREGATOR_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_signup"}'

Success Response

{
  "status": "ok"
}

Ready to integrate?

Check out Language Examples for production-ready helper functions in JavaScript, Python, PHP, Ruby, Go, and Rust.

Event Naming

Eventkiwi accepts any event name you send. There are no strict naming conventions—use whatever makes sense for your application.

Only Requirement

Event names must be URL-compatible (if using GET requests) and not cause HTTP 414 errors (URL too long).

Recommended Practices

While not enforced, these practices help keep your events organized:

• Be descriptive - user_signup is clearer than event1
• Stay consistent - Use the same style across your application
• Keep it reasonable - Very long names may be hard to read in reports

Examples

All of these work fine:

// Lowercase with underscores
await sendEvent('user_signup');

// CamelCase
await sendEvent('UserSignup');

// Kebab-case
await sendEvent('user-signup');

// Spaces (encoded in URLs)
await sendEvent('user signup');

// Mixed
await sendEvent('User_Signup_Event');

Choose what works best for your team and stick with it.

Response Format

Success Response (201 Created)

{
  "status": "ok"
}

Error Responses

400 Bad Request - Missing Parameters

{
  "error": "Missing required parameters"
}

POST requests return "Missing required parameters (name, _apikey, _id)".

Cause: Missing _id, _apikey (or Bearer token), or name. On POST, a body that isn't valid JSON is treated as empty, so this is also what you get if the JSON is malformed and name isn't in the query string.

401 Unauthorized - Invalid API Key

{
  "error": "Invalid API key"
}

Cause: The API key is incorrect.

404 Not Found - Invalid Aggregator

{
  "error": "Invalid aggregator"
}

Cause: The aggregator ID doesn't exist or doesn't belong to your account.

429 Too Many Requests - Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "limit": 5,
  "remaining": 0,
  "resetTime": 1640995201000
}

Cause: More than 5 requests in a second. Wait until resetTime (Unix milliseconds). See Limits.

403 Forbidden - Plan Limit Exceeded

{
  "error": "Plan limit exceeded",
  "currentCount": 100,
  "limit": 100,
  "remaining": 0
}

Cause: Your event allowance is used up. Retrying won't help until it resets or you upgrade. See Limits.

500 Internal Server Error

{
  "error": "Internal server error"
}

Cause: Something went wrong on our end. Try again or contact support.

Common Use Cases

User Authentication Events

Track user authentication flows:

• user_signup - User creates an account
• user_login - User signs in
• user_logout - User signs out
• password_reset - Password reset requested

E-commerce Events

Monitor your sales funnel:

• cart_add_item - Item added to cart
• checkout_started - User begins checkout
• checkout_completed - Purchase finalized
• order_shipped - Order dispatched

Application Monitoring

Track system health and operations:

• api_error - API request failed
• job_completed - Background task finished
• backup_created - Database backup completed
• health_check_passed - System health verified

Testing Events

You can test your event integration using cURL:

# Quick test with URL parameters
curl "https://app.eventkiwi.com/api/event?_id=YOUR_AGGREGATOR_ID&_apikey=YOUR_API_KEY&name=test_event"

# Test with Bearer token
curl -X POST "https://app.eventkiwi.com/api/event?_id=YOUR_AGGREGATOR_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "test_event"}'

Open the Event Log in the app to check the event arrived, with its tags. Each test event counts against your allowance.

Next Steps

• Language Examples - Production-ready helper functions for your language
• Event Tags - Learn how to add metadata to your events for better filtering and insights
• Authentication - Review authentication options in detail