Event Sinks API

Delivery is not live yet. You can create and store an event sink configuration today — the credential is encrypted at rest and the config round-trips through GET/PATCH — but the worker that produces events to Kafka or POSTs them to an HTTP collector has not shipped. No events are delivered to a configured sink, and the run-status fields (last_run_at, last_run_status, last_produced_count, consecutive_failures) stay null until it does. Do not configure a sink expecting live delivery. To receive events now, use per-event webhooks. This page documents the configuration surface; we’ll announce here when delivery goes live.

An event sink streams the platform event taxonomy — the same message.*, call.*, … events the per-event webhooks fan out — to infrastructure you already run. Instead of standing up an HTTP receiver per webhook, point a sink at your own Kafka topic or a batch HTTP collector and consume every subscribed event from one place. Two transports are available, addressed by kind:

kafka — once delivery ships, events will be produced to a topic on your brokers. Each event will carry a deterministic partition key, so every event for one contact or conversation lands on the same partition and stays ordered.
http_batch — once delivery ships, events will be POSTed to your HTTPS collector as a JSON array, flushed at a configurable batch size.

Base path: /api/v1/developer/event-sinks Authentication: API key (X-API-Key) or session JWT. Requires an owner, admin, or developer role.

Method	Path	Purpose
`GET`	`/api/v1/developer/event-sinks/{kind}`	Read the current config for one sink
`PATCH`	`/api/v1/developer/event-sinks/{kind}`	Merge a partial config into one sink

{kind} is kafka or http_batch. Any other value returns 404.

The credential is write-only

The secret credential — a Kafka SASL password or an HTTP bearer token — is encrypted at rest and is never returned. A read surfaces a credentials_configured boolean instead. To set or rotate it, PATCH a credentials value; to clear it, PATCH credentials: "".

Read a sink

curl "https://api.orbit.devotel.io/api/v1/developer/event-sinks/kafka" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "credentials_configured": true,
    "events": ["message.*", "call.completed"],
    "destination": {
      "kind": "kafka",
      "topic": "orbit.events",
      "partition_key_path": "data.contact_id"
    },
    "brokers": ["broker-1.example.com:9092", "broker-2.example.com:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-producer",
    "last_run_at": null,
    "last_run_status": null,
    "last_produced_count": null,
    "last_error": null,
    "last_error_at": null,
    "consecutive_failures": null
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-27T09:15:00.000Z" }
}

Response fields

Field	Type	Description
`kind`	string	`kafka` or `http_batch`.
`enabled`	boolean	Whether the sink streams events.
`credentials_configured`	boolean	`true` when an encrypted secret is stored. The secret is never returned.
`events`	string[]	Event filter. Empty or a single `` means every event; otherwise an exact type (`message.sent`) or a `<prefix>.` glob (`message.*`).
`destination`	object	The record-shaping config — `topic` for `kafka`, `url` for `http_batch`.
`brokers`	string[]	Kafka bootstrap brokers as `host:port` (`kafka` only).
`sasl_mechanism`	string	`plain`, `scram-sha-256`, or `scram-sha-512` (`kafka` only).
`sasl_username`	string	Kafka SASL username (`kafka` only).
`last_run_at`	string \| null	When the sink last attempted delivery.
`last_run_status`	string \| null	`ok` or `failed`.
`last_produced_count`	number \| null	Events produced on the last run.
`last_error`	string \| null	Last delivery error, if any.
`last_error_at`	string \| null	When the last error occurred.
`consecutive_failures`	number \| null	Consecutive failed runs.

The last_* fields are run status only — they are read-only and ignored if sent in a PATCH. Until the delivery worker ships they always read null, as in the example above.

Decoded redaction — `credentials_configured`

Reads never return the stored secret — not credentials, not credentials_encrypted, nothing. The credentials_configured boolean is the only signal you get. A successful read of a sink whose credential is stored decodes to exactly this shape:

{
  "data": {
    "kind": "http_batch",
    "enabled": true,
    "credentials_configured": true,
    "events": ["*"],
    "destination": {
      "kind": "http_batch",
      "url": "https://collector.example.com/orbit/events",
      "max_batch_size": 200
    }
  },
  "meta": { "request_id": "req_…", "timestamp": "…" }
}

Treat credentials_configured: false as “this sink cannot deliver even when the worker ships”; treat true as proof the secret round-tripped — without ever seeing the secret itself.

Read via the SDKs

The typed SDK surface has no event-sink helper yet, so the same read goes through the SDK’s generic request() helper:

import { Orbit } from "@devotel-orbit/node";

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

const { data: sink } = await orbit.request<{ data: unknown }>(
  "GET",
  "/developer/event-sinks/kafka"
);

console.log(sink.credentials_configured); // boolean — never the secret

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/developer/event-sinks/kafka")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. request() attaches your API key, retries 429/5xx with backoff, and returns the same { data, meta } envelope a raw call returns. Raw curl works identically.

Define — then verify with a read (write-then-read)

A sink config write returns the resulting config, so checking its state inline is cheap — but a GET is the reliable way to confirm what is actually stored. Below, each PATCH is answered with the state a follow-up GET returns.

Kafka sink — write

curl -X PATCH "https://api.orbit.devotel.io/api/v1/developer/event-sinks/kafka" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "events": ["message.*", "call.completed"],
    "destination": {
      "kind": "kafka",
      "topic": "orbit.events",
      "partition_key_path": "data.contact_id"
    },
    "brokers": ["broker-1.example.com:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-producer",
    "credentials": "the-sasl-password"
  }'

Kafka sink — read after the write

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "credentials_configured": true,
    "events": ["message.*", "call.completed"],
    "destination": {
      "kind": "kafka",
      "topic": "orbit.events",
      "partition_key_path": "data.contact_id"
    },
    "brokers": ["broker-1.example.com:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-producer",
    "last_run_at": null,
    "last_run_status": null,
    "last_produced_count": null,
    "last_error": null,
    "last_error_at": null,
    "consecutive_failures": null
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-27T09:15:00.000Z" }
}

The secret you patched never appears — credentials_configured: true is your confirmation it round-tripped.

HTTP-batch sink — write

curl -X PATCH "https://api.orbit.devotel.io/api/v1/developer/event-sinks/http_batch" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "events": ["*"],
    "destination": {
      "kind": "http_batch",
      "url": "https://collector.example.com/orbit/events",
      "max_batch_size": 200
    },
    "credentials": "a-bearer-token"
  }'

HTTP-batch sink — read after the write

{
  "data": {
    "kind": "http_batch",
    "enabled": true,
    "credentials_configured": true,
    "events": ["*"],
    "destination": {
      "kind": "http_batch",
      "url": "https://collector.example.com/orbit/events",
      "max_batch_size": 200
    },
    "last_run_at": null,
    "last_run_status": null,
    "last_produced_count": null,
    "last_error": null,
    "last_error_at": null,
    "consecutive_failures": null
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-27T09:15:00.000Z" }
}

The collector url must be https and resolve to a public host — private and metadata addresses are rejected. Once delivery ships, the sink will POST a JSON array of event envelopes (up to max_batch_size per request) with Content-Type: application/json. PATCH is a merge: only the fields you send are written, so you can flip enabled or rotate credentials without resending the whole config. The destination.kind must equal the path {kind} — a Kafka topic config cannot be stored under http_batch. The response is the resulting config in the same shape as a read.

Delivery envelope — shape when the worker ships

The delivery worker has not shipped, so a configured sink receives nothing today. But the record it will produce is already defined — every event is serialized byte-identically to the webhooks envelope, so a consumer you write against that shape works unchanged once the worker ships:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-08-27T12:00:00Z",
  "data": {
    "message_id": "msg_xyz789",
    "channel": "sms",
    "status": "delivered",
    "state_class": "terminal",
    "is_terminal": true,
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Transport differences hit only the framing:

Kafka — one JSON record per event. The partition key resolves from your partition_key_path (falls back to the event id, then to a hash of the payload); headers carry the envelope flattened (x-orbit-event-type, plus any custom headers you configured).
HTTP batch — the flushed body is a JSON array of these envelopes, up to max_batch_size per POST.

Write your consumer against this shape now, and gate the whole flow on webhooks until delivery goes live — the envelope is the same either way. When the worker ships we will announce it in the warning block at the top of this page.

API Reference

All Endpoints

Event Sinks API: stream Orbit events to Kafka or HTTP

Event Sinks API

The credential is write-only

Read a sink

Response fields

Decoded redaction — `credentials_configured`

Read via the SDKs

Define — then verify with a read (write-then-read)

Kafka sink — write

Kafka sink — read after the write

HTTP-batch sink — write

HTTP-batch sink — read after the write

Delivery envelope — shape when the worker ships

See also

​Event Sinks API

​The credential is write-only

​Read a sink

​Response fields

​Decoded redaction — credentials_configured

​Read via the SDKs

​Define — then verify with a read (write-then-read)

​Kafka sink — write

​Kafka sink — read after the write

​HTTP-batch sink — write

​HTTP-batch sink — read after the write

​Delivery envelope — shape when the worker ships

​See also

Event Sinks API

The credential is write-only

Read a sink

Response fields

Decoded redaction — `credentials_configured`

Read via the SDKs

Define — then verify with a read (write-then-read)

Kafka sink — write

Kafka sink — read after the write

HTTP-batch sink — write

HTTP-batch sink — read after the write

Delivery envelope — shape when the worker ships

See also