Concept

CloudEvents

How Kite wraps incoming webhooks in the CloudEvents 1.0 standard for interoperability.

Every payload that Kite delivers is wrapped in the CloudEvents 1.0 specification — a CNCF standard for describing event data in a common way.

Why CloudEvents?

Raw webhooks from different providers look completely different. A Stripe payment_intent.succeeded event has nothing structurally in common with a GitHub push event. This means your code has to handle each provider differently.

Kite normalises all incoming webhooks into a single CloudEvent envelope, so your agent or application only needs to understand one shape — regardless of source.

The envelope

A Stripe payment_intent.succeeded event arrives from Kite like this:

json

{
  "specversion": "1.0",
  "type": "com.stripe.payment_intent.succeeded",
  "source": "https://api.stripe.com",
  "id": "018f3c2a-8f6d-7b33-9b8b-f0d2d5f3b2a1",
  "time": "2026-04-02T12:34:56Z",
  "datacontenttype": "application/json",
  "kitesummary": "payment_intent.succeeded $20.00",
  "data": { }
}

Key attributes

`specversion` — always "1.0", identifies this as a CloudEvent
`type` — dot-separated reverse-domain identifier, e.g. com.github.push
`source` — the originating service URL
`id` — Kite-assigned UUIDv7 delivery ID
`time` — ISO 8601 timestamp
`data` — the original webhook payload, verbatim

Kite extensions

Kite adds the following CloudEvent extension attributes:

`kitesummary` — a human-readable one-line summary generated by Kite
`kiteoriginalheaders` — a JSON string containing a safe allowlist of original request headers for proxy replay and debugging
`kiteseq` — the per-team stream sequence number added when events are delivered over the stream
`kitefedorigin`, `kitefedchain`, `kitefedhops` — federation metadata on events that traverse Kite federation

Streaming modes

By default, kite stream prints human-readable summaries. Use --json for full CloudEvent JSON:

bash

# Summary mode (default)
kite stream
# → [com.github.push] refs/heads/main — 1 commit(s)

# Full CloudEvent JSON
kite stream --json

# Compact one-liners
kite stream --compact

Interoperability

CloudEvents-native tools can consume Kite events directly:

OpenClaw — use the Kite skill with a socket or MCP adapter
MCP-aware agents — expose the event buffer through the mcp_server manifest sink
Knative / Dapr — CloudEvents are the native event format
Custom agents — parse the standard JSON envelope