Events API
Send typed events from servers, workers, or custom clients.
Last updated June 3, 2026
Use POST /api/v1/events for trusted backend events. Send an application identity in userId; send visitorId only when you have an opaque Grometrics visitor ID. If both are present, Grometrics binds or merges them before storing the event. For retryable events, send the event's own stable eventId; Grometrics automatically creates the internal deduplication key.
Workspace-scoped authentication
Send a workspace API key as a Bearer token and include `websiteId`. Grometrics verifies that the site or tracked app belongs to that workspace before accepting the request.
Replace YOUR_SITE_ID with your site ID from Settings > Tracking.
POST /api/v1/events
1curl https://usegrometrics.com/api/v1/events \2-H "Authorization: Bearer YOUR_API_KEY" \3-H "Content-Type: application/json" \4-d '{5"websiteId": "YOUR_SITE_ID",6"userId": "user_123",7"externalSessionId": "app_session_456",8"event": "project_created",9"eventId": "project_456",10"properties": { "plan": "pro" }11}'
Options / Configuration
| Field | Meaning | Required |
|---|---|---|
| visitorId | Opaque internal Grometrics visitor ID | visitorId or userId |
| userId | Customer-defined application ID resolved through identity links | visitorId or userId |
| externalSessionId | Site-scoped customer session correlation value; never a Session primary key | no |
| event / name | Custom event name | ✓ |
| eventId | Stable business event ID used for automatic retry deduplication | recommended for retryable events |
| properties | Structured event metadata | no |
Do not infer ID types from prefixes
Internal IDs are opaque. Put values in `visitorId`, `userId`, or `externalSessionId` according to who generated them, not what the string looks like. The server events endpoint rejects `sessionId`; use `externalSessionId` for customer-owned correlation.
Legacy event migration
Existing integrations that previously put an application user ID in `visitorId` can temporarily send `x-grometrics-identity-contract: legacy-user-id`. Grometrics treats that value as `userId` and creates or resolves an opaque internal visitor. New integrations should always send `userId` explicitly.
What happens next
Call identify at signup or login so earlier browser activity and later backend events share one visitor timeline. Identify API
Was this page helpful?