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": "2026-06-21T09:14:02.000Z",
    "last_run_status": "ok",
    "last_produced_count": 128,
    "last_error": null,
    "last_error_at": null,
    "consecutive_failures": 0
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-21T09: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 (the values shown above are illustrative of the eventual shape, not live output).

Configure a Kafka sink

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"
  }'

Configure an HTTP-batch sink

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"
  }'

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.

API Reference

All Endpoints

Event Sinks API

Event Sinks API

The credential is write-only

Read a sink

Response fields

Configure a Kafka sink

Configure an HTTP-batch sink

See also

​Event Sinks API

​The credential is write-only

​Read a sink

​Response fields

​Configure a Kafka sink

​Configure an HTTP-batch sink

​See also

Event Sinks API

The credential is write-only

Read a sink

Response fields

Configure a Kafka sink

Configure an HTTP-batch sink

See also