Skip to main content
RisingWave Events API is a lightweight HTTP API layer for ingesting data into RisingWave. It provides:
  • Simple HTTP ingestion into RisingWave tables (POST /v1/events)
  • SQL execution over HTTP for DDL/DML (POST /v1/sql)
The project lives at risingwavelabs/events-api.
If you want an ingestion endpoint built into RisingWave itself (and need provider-style webhook signature validation), see Ingest data from webhook.

​
When to use Events API

Use Events API when you want:
  • App → RisingWave over HTTP without introducing Kafka or another message broker.
  • NDJSON ingestion (one JSON object per line) to push many events in one request.
  • A single service that can both create tables (via HTTP SQL) and ingest events.

​
Prerequisites

  • A running RisingWave instance.
  • Network access from Events API to RisingWave.
  • A RisingWave DSN (Postgres-compatible connection string) for EVENTS_API_RW_DSN.

​
Compare with RisingWave webhook connector

OptionWhat you runHow you ingestBest for
RisingWave webhook connectorRisingWave (webhook listener enabled)connector = 'webhook' tablesSaaS webhooks + request validation/signatures
Events APIRisingWave + Events API servicePOST /v1/events?name=<table>General event ingestion, NDJSON, simple HTTP ingestion

​
Key endpoints

EndpointDescription
POST /v1/sqlExecute SQL statements (DDL/DML).
POST /v1/events?name=<table>Ingest one JSON object, or NDJSON (one JSON object per line) into a table.

​
Quick start

​
1. Run Events API

Make sure you have a running RisingWave instance, then start Events API with a RisingWave DSN: 
docker run --rm \
  -e EVENTS_API_RW_DSN=postgres://root:@localhost:4566/dev \
  -p 8000:8000 \
  --name events-api \
  risingwavelabs/events-api:v0.1.4

​
2. Create a table via HTTP SQL

curl -X POST \
  -d 'CREATE TABLE clickstream (
    user_id BIGINT,
    session_id STRING,
    page_url STRING,
    event_type STRING,
    timestamp TIMESTAMP,
    referrer STRING,
    device_type STRING
  )' \
  http://localhost:8000/v1/sql

​
3. Ingest events

​
Insert a single JSON event

curl -X POST \
  -d '{"user_id": 12345, "session_id": "sess_abc123", "page_url": "/products/laptop", "event_type": "page_view", "timestamp": "2024-01-15 10:30:00", "referrer": "https://google.com", "device_type": "desktop"}' \
  'http://localhost:8000/v1/events?name=clickstream'

​
Insert multiple events (NDJSON)

curl -X POST \
  --data-binary @- \
  'http://localhost:8000/v1/events?name=clickstream' << 'EOF'
{"user_id": 12345, "session_id": "sess_abc123", "page_url": "/products/laptop", "event_type": "page_view", "timestamp": "2024-01-15 10:30:00", "referrer": "https://google.com", "device_type": "desktop"}
{"user_id": 12345, "session_id": "sess_abc123", "page_url": "/products/laptop", "event_type": "click", "timestamp": "2024-01-15 10:30:15", "referrer": "", "device_type": "desktop"}
{"user_id": 67890, "session_id": "sess_xyz789", "page_url": "/products/phone", "event_type": "page_view", "timestamp": "2024-01-15 10:31:00", "referrer": "https://twitter.com", "device_type": "mobile"}
EOF

​
4. Query the ingested data

curl -X POST \
  -d 'SELECT * FROM clickstream ORDER BY timestamp DESC LIMIT 10' \
  http://localhost:8000/v1/sql

​
Configuration

Events API can be configured via environment variables.
VariableDescriptionDefaultRequired
EVENTS_API_PORTHTTP server port8000No
EVENTS_API_HOSTHTTP server host0.0.0.0No
EVENTS_API_RW_DSNRisingWave connection string-Yes
EVENTS_API_DEBUG_ENABLEEnable debug/profiling endpointsfalseNo
EVENTS_API_DEBUG_PORTDebug server port8777No

​
Production notes

  • Networking: Deploy Events API where it can reach RisingWave via the DSN you provide.
  • Security: If you expose Events API to the public internet, put it behind a gateway/reverse proxy and enforce authentication/authorization and rate limiting.
  • Schema: Events API inserts into existing RisingWave tables. Create tables first (for example, through POST /v1/sql).