​

Configure event sinks: Kafka or HTTP batch

​

What event sinks are vs webhooks

• Webhooks — per-endpoint HTTPS POSTs, one event per request, with an X-Orbit-Signature HMAC over each body. You register endpoints on an event list and each becomes a steeply-secured receiver.
• Event sinks — a single declared destination per transport (kafka or http_batch); a subscriber filter such as ["message.*"] decides which of the platform’s event taxonomy lands there. The Kafka transport is not an HTTP receiver at all, and the HTTP-batch transport gets a JSON array of events in one POST.

​

Choose destination — HTTP batch or Kafka

• HTTP batch fits a receiver you can stand up behind HTTPS: a Lambda-flavored endpoint, a log-collecting pipeline, an internal orchestration layer that accepts arrays. Tuning knob is max_batch_size (1–1000 events per POST body, default 100).
• Kafka fits a data plane that already runs brokers: you give Orbit the bootstrap brokers, a topic, and an optional SASL credential; Orbit produces one record per event keyed by your partition field so per-contact ordering holds.

​

Configure HTTP batch

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": ["message.*", "call.completed"],
    "destination": {
      "kind": "http_batch",
      "url": "https://collector.example.com/orbit/events",
      "max_batch_size": 200
    },
    "credentials": "a-bearer-token"
  }'

​

Node.js consumer for HTTP batch (payload-rich envelopes)

import express from "express";

const app = express();
app.use(express.json({ limit: "2mb" })); // batches arrive as JSON arrays

app.post("/orbit/events", (req, res) => {
  // Optional: verify the Bearer token you configured as the sink credential.
  if (req.headers.authorization !== `Bearer ${process.env.ORBIT_SINK_TOKEN}`) {
    return res.status(401).json({ error: "Bad token" });
  }
  const events = req.body; // always an array, up to max_batch_size entries
  for (const event of events) {
    switch (event.type) {
      case "message.delivered":
        markDelivered(event.data.message_id);
        break;
      case "message.failed":
        flagFailure(event.data.message_id, event.data.error_code);
        break;
      case "call.completed":
        recordCallOutcome(event.data.call_id);
        break;
    }
    // Dedupe on event.id — at-least-once means replays are re-deliveries.
  }
  return res.status(200).json({ received: events.length });
});

​

Configure Kafka

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": ["*"],
    "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",
    "credentials": "the-sasl-password"
  }'

• brokers — 1–16 bootstrap brokers as host:port, no scheme, no path.
• destination.topic — the Kafka topic to produce to; 1–249 chars, [A-Za-z0-9._-], and never . or ...
• destination.partition_key_path — optional. A dot-path into the event envelope used to derive the record’s partition key. Default chain: data.contact_id → data.conversation_id → data.message_id → data.call_id → data.to → event id. Co-locating one contact’s events on one partition is the ordering guarantee downstream consumers can rely on.
• sasl_mechanism + sasl_username + credentials — the SASL handshake. Mechanisms: plain, scram-sha-256, scram-sha-512. The password is the encrypted credential; the username is stored plaintext alongside the brokers. If your brokers are not SASL-protected, omit all three and the sink produces without authentication.

​

Python consumer (confluent-kafka)

import json
from confluent_kafka import Consumer

c = Consumer({
    "bootstrap.servers": "broker-1.example.com:9092",
    "group.id": "orbit-sink-consumer",
    "auto.offset.reset": "earliest",
    "security.protocol": "SASL_SSL",
    "sasl.mechanism": "SCRAM-SHA-512",
    "sasl.username": "orbit-producer",
    "sasl.password": "the-sasl-password",
})
c.subscribe(["orbit.events"])

while True:
    msg = c.poll(1.0)
    if msg is None:
        continue
    if msg.error():
        continue
    event = json.loads(msg.value().decode("utf-8"))
    # event["id"] — dedupe on this; at-least-once redelivers under retry.
    # msg.key() — the partition key (e.g. the contact_id), utf-8 bytes.
    # event["type"], event["created_at"], event["data"] — same envelope as webhooks.
    headers = dict(msg.headers() or [])
    event_type = headers.get("x-orbit-event-type", b"").decode("utf-8")
    handle(event, event_type)

​

Delivery semantics — batched, ordered, at-least-once

• Batched. http_batch groups up to max_batch_size envelopes per POST; Kafka produces one record per event but linger-batches them inside the producer. Either way, retries that haven’t yet exhausted their backoff can result in the same event appearing twice — dedupe on the envelope id.
• Partition-ordered. Kafka guarantees ordering only within a partition; that’s why the partition key exists (a single contact’s events are co-located). Ordering across two different contacts is not defined. http_batch delivers in flush order per tenant but a retry can interleave — rely on created_at for entity state, not receive order.
• Retries. A failed attempt (non-2xx on the HTTP POST, or a producer error on the Kafka send) is retried with exponential backoff, bounded at ~5s maximum delay, 3 attempts per record/batch. Each retry of the same event carries the identical serialized value — the bytes don’t change mid-flight.

​

Inspect deliveries + DLQ mechanics

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,
    "last_run_at": "2026-08-27T09:15:00Z",
    "last_run_status": "ok",
    "last_produced_count": 12,
    "last_error": null,
    "consecutive_failures": 0
  }
}

​

Event sink vs webhook — comparison

​

Production checklist

• Collector url (http_batch) or brokers + destination.topic (kafka) set and enabled.
• credentials_configured: true on a read — the secret round-tripped.
• events filter set to the tightest prefix you actually consume (message.*, not *, unless you genuinely handle all).
• Receiver dedupes on the envelope id — at-least-once re-delivers under retry.
• A nightly job reads the sink (GET /api/v1/developer/event-sinks/{kind}) and alerts on last_run_status: "failed" or a growing consecutive_failures.
• SASL credentials live in a secrets manager, not in source control.

​

Next steps

• Event Sinks API — full request/response field reference, credential handling
• Webhook fan-out — how one event fans out to webhooks, the events buffer, and sinks
• Webhooks overview — the per-event taxonomy this sink consumes
• Build a durable webhook consumer — the webhook-side counterpart