kite~/kite/docs
v0.2.2
DashboardGitHub
Guide

Test a Local App

Stream hosted Kite webhooks to an app running on your machine with the Kite CLI — no local Kite server required.

Kite is a hosted service: the relay runs in the Kite cloud, and your app, webhook receiver, or test script runs on your own machine. The Kite CLI connects the two. There is no local Kite server to install — the relay is closed-source and only runs on Kite's hosted infrastructure.

Receiving new events through Kite requires an internet connection to the hosted relay. This guide does not support offline webhook delivery or self-hosting the relay.

Prerequisites

  • The Kite CLI installed — see Installation
  • A local HTTP app listening on a port such as http://localhost:3000 (this guide uses a GitHub webhook handler as the example)

1. Log in

bash
kite login

This opens the hosted Kite sign-in flow in your browser. Approve the device to authenticate your CLI. An internet connection is required.

2. Create an endpoint

bash
kite endpoints create --source github

Kite returns a webhook_url on the hosted relay plus a one-time signing secret. Add both to the source's settings (for GitHub: Settings → Webhooks).

3. Forward hosted events to your local app

bash
kite proxy --source github --target http://localhost:3000/webhooks

The CLI streams events from the hosted relay over WebSocket and POSTs each one to your local target. Push a commit or reopen a pull request and you should see the request land on your localhost server.

4. Observe events without a target

If you just want to inspect payloads before wiring up your app, stream them to the terminal instead:

bash
kite stream --source github

This is the same flow the Quickstart covers.

Running assertions per event

Use the CLI's exec sink to run a script for every event — handy for smoke tests against a running local app:

bash
kite stream --source github --exec ./test/assert-event.sh

assert-event.sh reads the CloudEvent JSON from stdin and exits non-zero if something's off.

Why there's no local relay option

Everything above talks to the hosted relay. Kite does not offer a downloadable or self-hosted relay. If your test environment cannot reach the internet, test your own handler with local fixtures; that does not exercise Kite delivery. Both the CLI and SDK need access to the hosted service to send or receive new events.

See also

  • Quickstart — full first-webhook walkthrough
  • Deployment — running your app in production with Kite
  • Troubleshooting — common "CLI can't reach the relay" failures