GitHub Webhooks

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

# GitHub Webhooks

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

Prerequisites

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

Step 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.

Step 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.

Step 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:

[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"

Step 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.

Filtering event types

Stream only the events you care about:

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

Using 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

Metadata 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-verified: true