@octokit/webhooks

@octokit/webhooks is the official Octokit toolset for receiving and handling GitHub webhook events in Node.js. It verifies incoming webhook signatures, parses the payload against generated TypeScript types for every GitHub event and action, and dispatches to event-specific listeners so you never have to hand-write payload validation or event-name branching logic.

It ships framework-agnostic middleware for both Node’s http server and web-standard Request/Response environments (Deno, Bun, Cloudflare Workers), plus a receiver you can wire directly into an existing Express, Fastify, or serverless handler. Types are generated from GitHub’s official OpenAPI webhook schemas, so payload shapes stay in sync with GitHub’s own event definitions release over release.

What You Get

• Cryptographic signature verification of incoming webhook payloads via @octokit/webhooks-methods
• Generated TypeScript types for every GitHub webhook event and action, sourced from GitHub’s official OpenAPI webhook schema
• An event-emitter API (.on(eventName, handler)) for registering typed handlers per event and action
• Node.js middleware for wiring directly into an http/Express server
• Web-standard middleware (Request/Response) for Deno, Bun, and edge runtimes like Cloudflare Workers
• A verifyAndReceive() helper for manually verifying and dispatching a payload outside the built-in middleware

Common Use Cases

• Building a GitHub App or bot that reacts to repository events (pushes, PR opens, issue comments) with typed payload access
• Running webhook receivers on edge platforms (Cloudflare Workers, Deno Deploy) using the web-standard middleware instead of Node’s http module
• Securely verifying that incoming webhook requests actually originated from GitHub before processing them
• Building CI/CD or ChatOps automation that listens for specific GitHub event/action combinations and triggers workflows

Under The Hood

Architecture: The package centers on src/index.ts, which composes the Octokit event-emitter (from octokit’s shared webhooks-methods verification layer) with generated payload types in src/generated to expose a single Webhooks class; verify-and-receive.ts handles the actual signature-check-then-dispatch flow, while src/middleware/node and src/middleware/web provide two separate adapter layers so the same core verification/dispatch logic can sit behind either Node’s http.IncomingMessage or a standard web Request object.

Tech Stack: Written in TypeScript (97% of the codebase) and built with esbuild plus tsc for type declarations, it depends on @octokit/openapi-webhooks-types for auto-generated payload shapes, @octokit/webhooks-methods for HMAC signature verification, and @octokit/request-error for consistent error objects; releases are automated via semantic-release reading conventional commits.

Code Quality: Tests run under Vitest with separate unit and integration suites (test/unit, test/integration) plus fixture-driven payload tests (test/fixtures), and the project additionally validates itself against Node’s native test runner, Bun, and Deno test runners to guarantee cross-runtime behavior; a pretest lint step (Prettier) gates every test run.

API Design: The public API is a small, familiar event-emitter shape (webhooks.on('push', handler)) that will feel immediately familiar to Node developers, with the heavy lifting of type-safety handled transparently through generated types rather than requiring manual payload casting.