@octokit/webhooks-types

@octokit/webhooks-types provides TypeScript type definitions for GitHub’s webhook event payloads, covering everything from pushes and pull requests to security alerts and workflow runs. The types are generated automatically from JSON Schemas kept in sync with GitHub’s actual webhook payloads, so consumers get accurate, discriminated-union types like PushEvent, IssuesOpenedEvent, and PullRequestReviewEvent without hand-writing interfaces.

The package ships a single schema.d.ts file with zero runtime code and zero dependencies — it’s imported purely for compile-time type checking in webhook handlers, GitHub Apps, and CI bots that need to safely narrow on an event’s action field.

What You Get

• Full webhook coverage - Types for every GitHub webhook event GitHub publishes, from push and pull_request to dependabot_alert and workflow_run.
• Discriminated unions - Multi-action events are further split into per-action variants (e.g. IssuesOpenedEvent, IssuesClosedEvent) for precise narrowing.
• Zero runtime footprint - Ships only a generated .d.ts file with no dependencies, so it adds nothing to bundle size.
• Auto-regenerated from schemas - Types are compiled by json-schema-to-typescript from the community-maintained JSON Schemas in the same monorepo, so they track GitHub’s payload changes.

Common Use Cases

• Typing webhook handlers - Narrow an incoming WebhookEvent payload to a specific event/action to safely read fields like issue.title or pull_request.merged.
• Building GitHub Apps - Get compile-time safety across the dozens of event types a GitHub App or bot might receive.
• CI/CD bots - Type-check logic that reacts to workflow_run, check_suite, or deployment_status events.
• Webhook payload validation tooling - Pair the types with @octokit/webhooks or a custom Express/Fastify handler to catch payload-shape regressions at build time.

Under The Hood

Architecture The published package is one leaf of the octokit/webhooks monorepo’s generation pipeline: bin/octokit-schema.mts builds a consolidated JSON Schema from community-contributed payload definitions, and bin/octokit-types.mts compiles that schema into payload-types/schema.d.ts via json-schema-to-typescript, including a hand-assembled EventPayloadMap that maps each webhook event name to its generated interface. @octokit/webhooks-types itself is just that output directory packaged for npm — no source files, no build step at install time, and no code path beyond the type declarations.

Tech Stack The repo is TypeScript/Node (tsx for running .mts scripts), using json-schema-to-typescript and ajv/ajv-formats for schema compilation and validation, got for fetching upstream GitHub documentation, cheerio and turndown for scraping/converting docs into schema fragments, and semantic-release (with per-package pkgRoot npm plugins) to independently version and publish payload-types, payload-schemas, and payload-examples from one repo.

Code Quality The monorepo validates itself rather than the types package having its own test suite: test.mts uses ajv to assert every example in payload-examples matches a basic webhook-definition shape, and bin/validate-schema.mts/validate-payload-examples.mts cross-check the compiled schema against real payloads. CI runs this validation plus Prettier formatting and CodeQL analysis on every push. The types package itself has no runtime logic to unit test — its correctness is entirely a function of the schema-generation pipeline being validated.

What Makes It Unique Most API SDKs hand-write their types; this package instead treats GitHub’s webhook shapes as a machine-generated build artifact, with EventPayloadMap giving consumers a single indexable interface across every event/action combination and the README’s explicit strictNullChecks caveat documenting a real inference gotcha other generated-types packages often leave undocumented.