Guide

GitHub Webhooks

Step-by-step guide to streaming GitHub webhook events to your local development environment with Kite.

This guide walks through setting up GitHub webhooks and streaming them to your local machine using Kite.

// 01Prerequisites

Kite installed and authenticated (kite login)
A GitHub repository where you have admin access

// 02Step 1 — Create a Kite endpoint

bash

kite endpoints create --source github

Kite outputs:

A webhook URL — paste this into GitHub's webhook settings
A one-time signing secret — paste this into GitHub's webhook settings

Important: The signing secret is shown only once. Copy it before proceeding.

// 03Step 2 — Configure GitHub

1. Go to your repository on GitHub 2. Navigate to Settings → Webhooks → Add webhook 3. Set Payload URL to the Kite relay URL from the previous step 4. Set Content type to application/json 5. Paste the Secret from the previous step 6. Choose which events to send (or select "Send me everything") 7. Click Add webhook

GitHub will immediately send a ping event to verify the endpoint.

// 04Step 3 — Stream events

bash

kite stream --source github

Trigger a GitHub event — push a commit, open a PR, or create an issue. You'll see output like:

code

[com.github.push] refs/heads/main — 2 commit(s) by alice
[com.github.pull_request.opened] PR #17 — "Feature: add dark mode"
[com.github.issues.opened] Issue #18 — "Bug: login fails on Safari"

// 05Step 4 — Proxy to a local server

If your application has a local webhook handler, proxy events directly:

bash

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

Kite forwards each event as a POST request with the CloudEvent JSON body.

// 06Filtering event types

Stream only the events you care about:

bash

kite stream --source github --event-type com.github.pull_request.opened

// 07Using a manifest

For a persistent, reproducible setup, add Kite to your kite.json:

json

{
  "version": 1,
  "streams": [
    {
      "source": "github",
      "eventTypes": ["com.github.push", "com.github.pull_request"],
      "clientId": "my-macbook",
      "sink": { "type": "proxy", "target": "http://localhost:3000/api/webhooks/github" }
    }
  ]
}

Then run:

bash

kite run --manifest kite.json

// 08Metadata headers

When proxying, Kite adds these headers to each forwarded request:

x-kite-source: github
x-kite-event-type: com.github.push
x-kite-event-id: <delivery-id>
x-kite-team-id: <team-id>
CloudEvents binary metadata such as ce-id, ce-source, ce-type, ce-specversion, and ce-time