concepts / cloudevents

CloudEvents

Every webhook Kite delivers is wrapped in a CloudEvents v1.0 envelope. The original payload is preserved, unmodified, in the data field. This gives you a uniform event shape across all providers — one handler, many sources.

Why CloudEvents?

→One format. Match on type across Stripe, GitHub, Slack, and any other source without per-provider adapters.
→Interoperable. CloudEvents-native tools — Knative, Dapr, OpenClaw — consume your events directly.
→Source attribution. The source and type fields tell you exactly where an event came from and what it is.

Envelope example — Stripe payment

{
  "specversion": "1.0",
  "id": "evt_1AbCdEfGhIjKlMnO",
  "source": "https://api.stripe.com",
  "type": "com.stripe.payment_intent.succeeded",
  "time": "2026-04-06T12:00:00Z",
  "datacontenttype": "application/json",
  "kite-verified": "true",
  "kite-source": "my-stripe",
  "data": {
    "id": "pi_3AbC...",
    "amount": 2000,
    "currency": "usd",
    "status": "succeeded"
  }
}

Envelope example — GitHub push

{
  "specversion": "1.0",
  "id": "01HXYZ...",
  "source": "github.com/owner/repo",
  "type": "com.github.push",
  "time": "2026-04-06T13:14:15Z",
  "datacontenttype": "application/json",
  "kite-verified": "true",
  "kite-source": "my-github",
  "data": {
    "ref": "refs/heads/main",
    "commits": [ ... ]
  }
}

Field reference

Field	Type	Required	Description
`specversion`	string	✓	Always "1.0".
`id`	string	✓	Unique event ID. Used for deduplication.
`source`	URI	✓	Origin of the event (e.g. https://api.stripe.com).
`type`	string	✓	Dot-namespaced event type (e.g. com.stripe.payment_intent.succeeded).
`time`	timestamp	—	ISO 8601 timestamp when the event occurred.
`datacontenttype`	string	—	Content type of data. Usually "application/json".
`data`	any	—	The original webhook payload, unmodified.
`kite-verified`	boolean	—	Extension. "true" if HMAC signature passed.
`kite-source`	string	—	Extension. Kite source name that received the event.

Matching on type

The type field uses a reverse-DNS naming scheme: com.{provider}.{event}. You can match exactly or with a glob in your manifest routes:

// Exact match
{ "match": { "type": "com.stripe.payment_intent.succeeded" } }

// Glob — all Stripe events
{ "match": { "type": "com.stripe.*" } }

// Multiple providers
{ "match": { "type": "com.stripe.*|com.github.*" } }

Full event schemas per provider are in the Event Payload Reference. Learn how Kite ensures payloads are authentic in Security.