Events

{
  "data": [
    {
      "id": "1755008400000-0",
      "type": "message.delivered",
      "ts": 1755008400000,
      "data": {
        "message_id": "msg_9f2a1c4e",
        "channel": "sms",
        "to": "+1415555****",
        "from": "+1415000****",
        "status": "delivered",
        "delivered_at": "2026-08-12T14:20:00.000Z"
      }
    },
    {
      "id": "1755008300000-0",
      "type": "call.completed",
      "ts": 1755008300000,
      "data": {
        "call_id": "call_3f7b1d2c",
        "direction": "outbound",
        "duration_seconds": 184,
        "status": "completed"
      }
    },
    {
      "id": "1755008200000-0",
      "type": "message.failed",
      "ts": 1755008200000,
      "data": {
        "message_id": "msg_8c3d2b1a",
        "channel": "whatsapp",
        "to": "+1415566****",
        "status": "failed",
        "error_code": "CARRIER_REJECTED"
      }
    }
  ],
  "meta": {
    "request_id": "req_evt_page1",
    "timestamp": "2026-08-12T14:30:00.000Z",
    "pagination": {
      "cursor": "1755008200000-0",
      "has_more": true,
      "total": 3
    }
  }
}

{
  "data": [
    {
      "id": "1755008400000-0",
      "type": "message.delivered",
      "ts": 1755008400000,
      "data": {
        "message_id": "msg_9f2a1c4e",
        "channel": "sms",
        "to": "+1415555****",
        "from": "+1415000****",
        "status": "delivered",
        "delivered_at": "2026-08-12T14:20:00.000Z"
      }
    },
    {
      "id": "1755008300000-0",
      "type": "call.completed",
      "ts": 1755008300000,
      "data": {
        "call_id": "call_3f7b1d2c",
        "direction": "outbound",
        "duration_seconds": 184,
        "status": "completed"
      }
    },
    {
      "id": "1755008200000-0",
      "type": "message.failed",
      "ts": 1755008200000,
      "data": {
        "message_id": "msg_8c3d2b1a",
        "channel": "whatsapp",
        "to": "+1415566****",
        "status": "failed",
        "error_code": "CARRIER_REJECTED"
      }
    }
  ],
  "meta": {
    "request_id": "req_evt_page1",
    "timestamp": "2026-08-12T14:30:00.000Z",
    "pagination": {
      "cursor": "1755008200000-0",
      "has_more": true,
      "total": 3
    }
  }
}

Track events power more than campaigns and journeys. They feed the Customer-360 workspace timeline, where one snapshot call aggregates a contact’s events, conversations, voice calls, tickets, and more into a single workspace view.

Worked sequences

The four operations below are a complete walk-through of the Events surface, in the order an integration typically uses them: page through history, look up a single event, tail the live stream, and publish your own events. Every response below is a worked copy of the wire shape, and the Node examples route through the SDK’s orbit.request() helper.

List event history — GET /events

Page through the tenant’s recent-event history newest-first. The first request omits cursor; each page’s meta.pagination.cursor feeds the next request while has_more is true. Step 1 — first page

curl -X GET "https://api.orbit.devotel.io/api/v1/events/?limit=3" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const page1 = await orbit.request('GET', '/events/?limit=3')

Response (first page)

{
  "data": [
    {
      "id": "1755008400000-0",
      "type": "message.delivered",
      "ts": 1755008400000,
      "data": {
        "message_id": "msg_9f2a1c4e",
        "channel": "sms",
        "to": "+1415555****",
        "from": "+1415000****",
        "status": "delivered",
        "delivered_at": "2026-08-12T14:20:00.000Z"
      }
    },
    {
      "id": "1755008300000-0",
      "type": "call.completed",
      "ts": 1755008300000,
      "data": {
        "call_id": "call_3f7b1d2c",
        "direction": "outbound",
        "duration_seconds": 184,
        "status": "completed"
      }
    },
    {
      "id": "1755008200000-0",
      "type": "message.failed",
      "ts": 1755008200000,
      "data": {
        "message_id": "msg_8c3d2b1a",
        "channel": "whatsapp",
        "to": "+1415566****",
        "status": "failed",
        "error_code": "CARRIER_REJECTED"
      }
    }
  ],
  "meta": {
    "request_id": "req_evt_page1",
    "timestamp": "2026-08-12T14:30:00.000Z",
    "pagination": {
      "cursor": "1755008200000-0",
      "has_more": true,
      "total": 3
    }
  }
}

Step 2 — page forward while has_more is true

Node.js

const page2 = await orbit.request(
  'GET',
  `/events/?limit=3&cursor=${encodeURIComponent(page1.meta.pagination.cursor)}`,
)

Send the cursor verbatim — it is the id of the last event from the prior page (<ms>-<seq> form). When has_more comes back false, history is exhausted.

Get event details — GET /events/:id

Fetch one event by its id — either the canonical stream id from a list page (1755008400000-0) or a legacy publisher-minted evt_* id. Both resolve against the same history window. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/events/1755008400000-0" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/events/1755008400000-0', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/events/1755008400000-0", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/events/1755008400000-0", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/events/1755008400000-0')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/events/1755008400000-0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Response

{
  "data": {
    "id": "1755008400000-0",
    "type": "message.delivered",
    "ts": 1755008400000,
    "data": {
      "message_id": "msg_9f2a1c4e",
      "channel": "sms",
      "to": "+1415555****",
      "from": "+1415000****",
      "status": "delivered",
      "delivered_at": "2026-08-12T14:20:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_evt_get",
    "timestamp": "2026-08-12T14:31:00.000Z"
  }
}

An id outside the retained history window returns a 404 with the NOT_FOUND error envelope.

Live tail — GET /events/stream (SSE)

For a live dashboard, open a Server-Sent Events connection instead of polling. The stream replays anything buffered after your Last-Event-ID (or ?lastEventId=), then tails events as they publish. A 30-second : heartbeat comment frame keeps the connection open between events. curl (server-side, secret API key)

curl -N \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  "https://api.orbit.devotel.io/api/v1/events/stream?types=message.delivered,message.failed"

Browser EventSource (Clerk session cookie)

const es = new EventSource(
  'https://api.orbit.devotel.io/api/v1/events/stream?types=message.delivered',
  { withCredentials: true },
)

es.addEventListener('message.delivered', (e) => {
  const event = JSON.parse(e.data)
  console.log(e.lastEventId, event.data.status, event.data.message_id)
  // persist e.lastEventId — pass it back as ?lastEventId= on reconnect
})

Non-browser Node clients can keep a durable cursor on the ?lastEventId= query parameter (EventSource re-sends it as the Last-Event-ID header automatically). Sample stream frames

: heartbeat

id: 1755008400000-0
event: message.delivered
data: {"id":"1755008400000-0","type":"message.delivered","ts":1755008400000,"data":{"message_id":"msg_9f2a1c4e","channel":"sms","status":"delivered"}}

id: 1755008461000-0
event: message.failed
data: {"id":"1755008461000-0","type":"message.failed","ts":1755008461000,"data":{"message_id":"msg_7b4e9d3c","channel":"sms","status":"failed","error_code":"CARRIER_REJECTED"}}

Each frame is id:, event:, and data: separated by a blank line. On reconnect, re-send the last id you saw and the replay pass fills the gap before the live tail resumes. ?types= narrows both the replay and the live tail to the comma-separated event types.

Publish a tracked event — POST /events/track

Record a domain event for a contact — Order Placed, Subscription Renewed, Trial Converted — to drive lifecycle campaigns, journey triggers, and the customer-360 timeline. The body is validated against the same per-event contract the schema registry publishes; GET /events/schema-registry returns that catalog (dialect, per-type JSON Schema, example payload, and a drift-detecting fingerprint) so you can pin the shape client-side. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/events/track/" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/events/track/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/events/track/", headers=headers, json={
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/events/track/", bytes.NewBuffer([]byte(`{
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/events/track/')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/events/track/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "event": "Order Placed",
  "contact_email": "ana@example.com",
  "properties": {
    "order_id": "ord_1138",
    "total": 49,
    "currency": "USD"
  },
  "message_id": "msg_client_42",
  "timestamp": "2026-08-12T14:22:18.000Z"
}
JSON);
echo curl_exec($ch);

Response

{
  "data": {
    "received": true,
    "event_id": "evt_9c2d4e6f8a0b1c3d4e5f6a",
    "contact_id": "con_4f2a8c1d9e3b",
    "deduped": false
  },
  "meta": {
    "request_id": "req_evt_track",
    "timestamp": "2026-08-12T14:22:19.000Z"
  }
}

event is required; contact_email or contact_phone identify the contact (unmatched events are still recorded and stitch later). properties carries event attributes, message_id is a client-side dedup key, and timestamp is the client event time — the server’s receipt time remains the canonical sort key. A retry with the same Idempotency-Key or message_id returns deduped: true without writing a second row. The registry is fetched with a plain GET:

curl -X GET "https://api.orbit.devotel.io/api/v1/events/schema-registry" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const registry = await orbit.request('GET', '/events/schema-registry')

Poll data.catalog_version to detect any change to the platform event contract cheaply, then diff each schema’s fingerprint to see which event types moved.

API Reference

All Endpoints

Worked sequences

List event history — GET /events

Get event details — GET /events/:id

Live tail — GET /events/stream (SSE)

Publish a tracked event — POST /events/track

​Worked sequences

​List event history — GET /events

​Get event details — GET /events/:id

​Live tail — GET /events/stream (SSE)

​Publish a tracked event — POST /events/track

Worked sequences

List event history — GET /events

Get event details — GET /events/:id

Live tail — GET /events/stream (SSE)

Publish a tracked event — POST /events/track