Send events from a server
Send events that happen on your servers, such as payments, with an API key, so they count in goals and funnels next to website events.
Reference3 min read
Some things happen on a server rather than in a browser: a payment your payment provider confirms, an order your shop system ships, a booking another system makes. The server API takes those events, so they count in goals, revenue and the monthly events like events from the script. It works on every plan.
Make a key
An Admin opens API keys under Developers, selects New API key, names it after the server, such as Shop server, and ticks Send events. The key, starting with ins_live_, is shown once: keep it in your server's settings, never in a web page or an app. Make one key per server, so you can remove one without stopping the others. See API keys.
Send events
curl https://api.bifrostorbit.com/insights/v1/server/events \ -H "Authorization: Bearer ins_live_…" \ -H "Content-Type: application/json" \ -d '{ "site": "SITE_KEY", "events": [ { "id": "order-1042", "name": "Order paid", "revenue": 129.5, "currency": "EUR", "properties": { "items": 3 } } ] }'It answers 202 with how many events were taken: { "data": { "accepted": 1, "repeated": 0 } }. While the organisation's Insights Orbit trial or plan has ended, it answers 204 with no body and stores nothing, so your server needs no special handling.
siteWhat it is
The site's key, from Install. The site must be in the key's organisation.
eventsWhat it is
One to 100 events. The whole request can be up to 256 KB.
nameWhat it is
The event's name, such as
Order paid, as in insights.track. Required.idWhat it is
Your own id for the event, such as the order number, up to 80 letters, digits,
., _, : or -. An event with an id already sent for the site in the last eight days is counted once, so you can safely send again after a timeout.timestampWhat it is
When it happened, as a time such as
2026-10-21T09:30:00Z or milliseconds since 1970. Up to seven days back. Now when left out.propertiesWhat it is
Details, as in
insights.track: up to 30, each text, a number or true or false.revenue, currencyWhat it is
Money, with a three-letter currency code, as in
insights.track.urlWhat it is
The page it belongs to, on one of the site's addresses. The site's address when left out.
countryWhat it is
A two-letter country code, such as
DE, if you know it.userIdWhat it is
Your user id for the person, used only when the site has known users switched on and kept only in a scrambled form.
| Field | What it is |
|---|---|
site | The site's key, from Install. The site must be in the key's organisation. |
events | One to 100 events. The whole request can be up to 256 KB. |
name | The event's name, such as Order paid, as in insights.track. Required. |
id | Your own id for the event, such as the order number, up to 80 letters, digits, ., _, : or -. An event with an id already sent for the site in the last eight days is counted once, so you can safely send again after a timeout. |
timestamp | When it happened, as a time such as 2026-10-21T09:30:00Z or milliseconds since 1970. Up to seven days back. Now when left out. |
properties | Details, as in insights.track: up to 30, each text, a number or true or false. |
revenue, currency | Money, with a three-letter currency code, as in insights.track. |
url | The page it belongs to, on one of the site's addresses. The site's address when left out. |
country | A two-letter country code, such as DE, if you know it. |
userId | Your user id for the person, used only when the site has known users switched on and kept only in a scrambled form. |
What is different from the script
- There is no visitor and no visit. Insights Orbit doesn't read an address or a browser from your server's request, so server events don't change the numbers of visitors, visits or bounce rate. In reports and the raw event API their device is
server. - Each server event counts as one goal completion of its own, so ten paid orders are ten completions.
- With known users switched on and a
userId, a server event belongs to the person, so a funnel counted by known users can start on a page and end with a payment.
Errors
400Why
The body isn't JSON or the events aren't valid. The message says which field.
401Why
No key, or a key that was removed.
403Why
The key may only read events.
404Why
The site isn't in the key's organisation, or is in the bin.
413Why
The request is over 256 KB.
429Why
More than 600 requests a minute with one key. Wait a minute, or send more events in each request.
| Status | Why |
|---|---|
400 | The body isn't JSON or the events aren't valid. The message says which field. |
401 | No key, or a key that was removed. |
403 | The key may only read events. |
404 | The site isn't in the key's organisation, or is in the bin. |
413 | The request is over 256 KB. |
429 | More than 600 requests a minute with one key. Wait a minute, or send more events in each request. |
Was this page helpful?
Read next
API keysMake a key that sends events from your servers, reads raw events for your own tools, or both, and remove it when it is no longer used.Send your own eventsCount things people do with one line of code, with details and revenue, and use them in goals.Send user ids for known usersAttach your own user id to events from the browser and from your servers, so signed-in people are followed across days and devices.Read raw eventsRead every event your sites collected, page by page, with an API key, for your own data tools.Set up goalsSay what counts as success on a site, such as reaching a thank-you page or sending a form, and see how often visits get there.