API & Server-side Setup
Send events from your backend or any server to Hardal with an HTTP POST to the /collect endpoint.
When to use the API
Use the API for events that happen on your server instead of in the browser. Send an event when a payment webhook confirms an order or your CRM creates a lead. You can also use it for privacy-sensitive events that you don't want to handle client-side.
The endpoint and payload are identical to Mobile Setup. Both send an HTTP POST to /collect.
Privacy by default
You can send server events without a known user identity. Include userId or other identity fields only when your consent rules allow it. If a destination requires consent, send the applicable consent state with the event.
Consent Signals
When to send consent and what each signal changes.
Server event endpoint
POST https://analytics.yourdomain.com/collect
Use your first-party URL. This is the same data-host-url shown in the Dashboard.
| Header | Required | Value |
|---|---|---|
Content-Type | Yes | application/json |
tenant-id | Yes | Tenant ID from Setup |
x-virgo-session-id | No | Stable UUID for the current session |
x-virgo-consent | No | granted or denied |
If x-virgo-session-id is omitted, Hardal creates a session ID. Send x-virgo-consent: granted when identity processing is allowed and denied when it is not. If the header is omitted, Hardal reuses a valid first-party identity cache for the same Tenant ID and Source ID; without that cache, it removes userId and visitorId before processing.
Server event payload
{
"type": "event",
"eventName": "purchase",
"payload": {
"sourceId": "your-source-id",
"title": "Order Confirmed",
"hostname": "www.yourdomain.com",
"url": "https://www.yourdomain.com/order/confirmation",
"referrer": "https://www.yourdomain.com/cart",
"timestamp": 1773914400000,
"timezone": "Europe/Istanbul",
"data": {
"transaction_id": "ORD-20260615-7891",
"value": 214.98,
"currency": "USD"
}
}
}
One event cannot contain both a non-empty items array and a non-empty leads array.
Send a server event
curl -X POST https://analytics.yourdomain.com/collect \
-H "Content-Type: application/json" \
-H "tenant-id: your-tenant-id" \
-H "x-virgo-session-id: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"type": "event",
"eventName": "generate_lead",
"payload": {
"sourceId": "your-source-id",
"title": "Contact Form",
"hostname": "www.yourdomain.com",
"url": "https://www.yourdomain.com/contact",
"timestamp": 1773914400000,
"data": {
"lead_id": "LEAD-12345",
"value": 500,
"currency": "USD"
}
}
}'
A valid request returns 202 Accepted. The response includes the accepted event count, generated Event IDs and Source IDs, and the applied consent status. It also includes the timestamp, request path, and request ID.
Send a batch
Send multiple events to the same endpoint by wrapping them in an events array. The same headers and field rules apply to every event.
{
"events": [
{
"type": "event",
"eventName": "page_view",
"payload": {
"sourceId": "your-source-id",
"url": "https://www.yourdomain.com/products",
"timestamp": 1773914400000,
"data": {}
}
},
{
"type": "event",
"eventName": "purchase",
"payload": {
"sourceId": "your-source-id",
"url": "https://www.yourdomain.com/order/confirmation",
"timestamp": 1773914460000,
"data": {
"transaction_id": "ORD-20260615-7891",
"value": 214.98,
"currency": "USD"
}
}
}
]
}
Send Events API
Full reference and a live playground for the /collect endpoint.