Server-to-Server API: Events
Absinthe’s Server-to-Server API lets your backend send user activity directly into Absinthe as events. This is the cleanest option when the behavior you want to reward happens inside your product (or any system you control) and therefore isn’t visible to Absinthe through a native integration or an on-chain adapter. Right now, events are registered and scoped per campaign (you tag requests with a campaign when registering/listing events). We’re shipping an update soon where event data can be sent without being registered under a particular campaign, which will make event ingestion much easier for teams running multiple campaigns or running always-on tracking.Why integrate the Server-to-Server API?
You should use events when you want to measure product-native behavior such as session length, login frequency, onboarding completion, identity connections, in-app progress states, purchases, or any custom transaction/engagement signals you track internally. If Absinthe can’t reliably observe it through an adapter or a third-party integration, these events are how you give Absinthe that visibility.API keys (Workspace level)
All requests to the Events API require an API key. You create and manage keys at the workspace level under Workspace → API Keys. Keep keys server-side. Treat them like production secrets.Events workflow
1) Register an event (per campaign)
Before you can send event data, you create a registered event inside the campaign. This defines the event’s name and purpose, and gives you anevent_id you’ll use when submitting data.
Endpoint: POST /events
This step is campaign-scoped today because the event registry is campaign-scoped. (This is the part that will become optional once the “no campaign registration required” ingestion update ships.)
2) List registered events (per campaign)
Use this to verify what you’ve already registered and to fetch theevent_id values for your integration.
Endpoint: GET /events
3) Submit event data
Once you have anevent_id, you can submit raw activity values for users. This is the data Absinthe later uses inside Campaign → API Activity Tracking → Activity Rewards to turn raw amounts into rewards (fixed-per-event, multiplier, etc.).
Endpoint: POST /events/:event_id/data
The amount is intentionally “raw.” For a game it could be monsters killed, matches won, damage dealt, or XP earned. For a SaaS product it might be session seconds, number of actions taken, dollars spent, or successful referrals. You decide what the raw metric should represent; Absinthe’s reward configuration decides how that raw metric maps into points.
Important notes for engineers
Raw metrics vs reward points
The Events API is for metrics, not “points.” Your event’samount should be the most truthful representation of the activity (seconds, count, dollars, etc.). Later, campaign managers choose whether to ignore amount and issue a fixed reward per event, multiply it, or pass it through 1:1.
Rate limits and safety
The submit endpoint returns rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) when applicable. Even with rate limiting, you should also design your event emission to avoid runaway spam (debounce noisy client events; aggregate server-side where reasonable; use idempotency in your own pipeline if you retry).
Campaign scoping today, simpler ingestion coming soon
Today, you register/list events withX-Campaign-ID, and then submit to :event_id (which is inherently tied to a campaign). Soon, you’ll be able to send event data without first anchoring it to a campaign registry, which will remove friction for multi-campaign setups and let teams implement “always-on” tracking once at the workspace level.
Minimal integration pattern
A typical production setup looks like this: your backend receives user actions → you map them to a small set of canonical event types → you submit those events to Absinthe with the correct identity and a rawamount → your campaign manager attaches rewards to those events inside the campaign UI