API Documentation

Rivulet event delivery platform — v2 API

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer rv_live_your_api_key

Keys are available in your account settings. Use rv_test_ prefixed keys for the sandbox environment.

Unauthenticated requests return 401.

Base URL

https://x.link.lihj.link/v2

Endpoints

POST /v2/events

Publish an event to one or more channels.

curl -X POST https://x.link.lihj.link/v2/events \
  -H "Authorization: Bearer rv_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "orders",
    "type": "order.completed",
    "data": {
      "order_id": "ord_8a3b2c",
      "amount": 4900,
      "currency": "usd"
    }
  }'

Returns 202 Accepted with an event ID.

{
  "id": "evt_1a2b3c4d",
  "status": "queued",
  "created_at": "2026-01-15T10:32:00Z"
}

GET /v2/events/{event_id}

Retrieve an event by ID, including delivery attempts and status.

curl https://x.link.lihj.link/v2/events/evt_1a2b3c4d \
  -H "Authorization: Bearer rv_live_xxxxx"

GET /v2/events

List events. Supports pagination via cursor. Returns up to 50 per request.

Parameter	Type	Description
`channel`	string	Filter by channel name
`type`	string	Filter by event type
`since`	ISO 8601	Events after this timestamp
`cursor`	string	Pagination cursor

POST /v2/webhooks

curl -X POST https://x.link.lihj.link/v2/webhooks \
  -H "Authorization: Bearer rv_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/rivulet",
    "channels": ["orders", "payments"],
    "events": ["order.completed", "payment.failed"]
  }'

GET /v2/webhooks

List registered webhook endpoints for your account.

DELETE /v2/webhooks/{webhook_id}

Remove a webhook endpoint. Pending deliveries will be cancelled.

Real-time Streaming

For low-latency event consumption, use a WebSocket connection instead of polling.

WS /v2/stream

Open a persistent WebSocket connection. Authenticate with the token query parameter.

wss://x.link.lihj.link/v2/stream?token=rv_live_xxxxx

Subscribe to channels after connecting:

{
  "action": "subscribe",
  "channels": ["orders", "payments"]
}

Events arrive as JSON frames:

{
  "id": "evt_1a2b3c4d",
  "channel": "orders",
  "type": "order.completed",
  "data": { ... },
  "created_at": "2026-01-15T10:32:00Z"
}

If the connection drops, reconnect with exponential backoff starting at 1 second. Include Last-Event-ID to resume from where you left off.

Rate Limits

Plan	Requests/min	Events/day	WS connections
Standard	1,000	100,000	10
Pro	5,000	1,000,000	50
Enterprise	Custom	Custom	Custom

Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset.

Errors

Code	Description
`400`	Invalid or missing parameters
`401`	Missing or invalid API key
`403`	Insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal error — try again later

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}