Octokit Webhooks

A webhook definition describes the available events for a specific resource. It typically includes:

• name: The name of the webhook event (e.g., issues).
• actions: A list of specific actions that trigger this webhook (e.g., opened, edited, closed).
• examples: An array of example payloads that demonstrate the data structure for different actions within that event.

Each example payload contains the specific data related to the action, such as the resource being modified, the repository context, and the sender of the event.

{
  "name": "issues",
  "actions": [
    "opened",
    "edited",
    "deleted"
  ],
  "examples": [
    {
      "action": "edited",
      "issue": { ... },
      "repository": { ... },
      "sender": { ... }
    }
  ]
}

To select a schema for comparison, you must provide an interface property path. This path consists of the name of the interface, followed by a dot-separated path to the specific property you want to inspect.

Selection Patterns

• Specific Property: InterfaceName.property.subProperty
• Entire Interface: InterfaceName (selects the schema for the whole interface)

Example

If you have the following interfaces:

interface PullRequest {
  id: string;
  title: string;
  number: string;
  state: "open";
}

interface PullRequestCloseEvent {
  action: "close";
  pull_request: {
    id: string;
    title: string;
    number: string;
    state: "closed";
  };
}

To compare the pull_request property of the close event against the base PullRequest interface, run:

bin/diff-interface-schemas.mts PullRequest PullRequestCloseEvent.pull_request

When using ajv in strict: true mode to validate webhook events, you must manually add support for specific custom keywords used in the Octokit schemas. Specifically, you need to include ajv-formats for standard formats and manually register the tsAdditionalProperties keyword to prevent "unknown keyword" errors.

import type { WebhookEvent } from "@octokit/webhooks-types";
import * as githubWebhookSchema from "@octokit/webhooks-schemas";
import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ strict: true });

addFormats(ajv);
// Required to prevent 'unknown keyword' errors in strict mode
avj.addKeyword("tsAdditionalProperties");

const validate = ajv.compile<WebhookEvent>(githubWebhookSchema);

You can download the latest webhook definitions and payload schemas directly from unpkg to use in your own tools or validation logic.

• Webhook definitions index: index.json
• Webhook payload schemas: schema.json

Links:

• index.json
• schema.json

If you want to verify whether any JSON payloads or schemas require formatting without actually modifying the files on disk, use the --check flag with the formatting script.

bin/format-with-prettier.mts --check

To access the JSON schema for GitHub webhook payloads, install and import the @octokit/webhooks-schemas package. This provides the machine-readable specifications for all GitHub webhook events.

// Use Node.js require:
const SCHEMA = require("@octokit/webhooks-schemas");

// Or ESM/TypeScript import:
import SCHEMA from "@octokit/webhooks-schemas";

The bin/extract-common-schema.mts utility extracts a specific property schema from an existing interface and saves it as a new "common" schema in schemas/common/. This is useful for deduplicating shared structures across different webhook event interfaces.

To use the tool, provide an "interface property path" (the interface name followed by a dot-separated path to the property) and the desired name for the new interface. By default, the tool will throw an error if a schema with the generated name already exists. Use the --overwrite flag to replace an existing schema.

bin/extract-common-schema.mts <interface property path> <interface name> [--overwrite]

# Example: Extracting the pull_request property from PullRequestOpenEvent into a PullRequest interface
bin/extract-common-schema.mts PullRequestOpenEvent.pull_request PullRequest

When using ajv in strict: true mode, it will throw an "unknown keyword" error for any keywords not explicitly defined. The Octokit webhook schemas use custom keywords provided by ajv-formats and a custom keyword tsAdditionalProperties. To prevent validation errors, you must register these keywords with your Ajv instance.

import type { WebhookEvent } from "@octokit/webhooks-types";
import * as githubWebhookSchema from "@octokit/webhooks-schemas";
import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ strict: true });

addFormats(ajv);
// Register the custom keyword used in the schemas
avj.addKeyword("tsAdditionalProperties");

const validate = ajv.compile<WebhookEvent>(githubWebhookSchema);