> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/github/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks and GitHub Apps

> How webhook and GitHub Apps documentation is generated from the OpenAPI and other automated pipelines.

Webhook event documentation and GitHub Apps endpoint documentation are both auto-generated from the OpenAPI stored in [`github/rest-api-description`](https://github.com/github/rest-api-description). They share the same `sync-openapi.yml` workflow as the REST pipeline, but write output to separate directories.

Several other documentation types — audit logs, secret scanning, and CodeQL CLI — have their own independent sync scripts.

## The shared OpenAPI pipeline

The `.github/workflows/sync-openapi.yml` workflow triggers three pipelines in a single run:

<CardGroup cols={3}>
  <Card title="REST" icon="code">
    Writes Markdown to `content/rest/` and data to `src/rest/data/`
  </Card>

  <Card title="Webhooks" icon="webhook">
    Writes data to `src/webhooks/data/`
  </Card>

  <Card title="GitHub Apps" icon="github">
    Writes data to `src/github-apps/data/`
  </Card>
</CardGroup>

All three pipelines are triggered by `npm run sync-rest`. For webhooks and GitHub Apps, the script writes to different output directories using the `-o` flag. Automated PRs carry the `github-openapi-bot` label.

## Webhooks pipeline

The webhooks pipeline generates documentation for `docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads`.

### Directory structure

```
src/webhooks/
├── components/    # React components for rendering webhook event pages
├── data/          # Auto-generated JSON files (do not edit manually)
├── lib/
│   └── config.json  # SHA of last synced rest-api-description commit
├── middleware/    # Express middleware for injecting webhook data
├── pages/         # Next.js page files
├── scripts/
│   └── sync.ts    # Pipeline entrypoint
└── tests/         # Vitest tests
```

The content file `content/webhooks-and-events/webhooks/webhook-events-and-payloads` can have manually authored frontmatter and an introductory paragraph. Automated content is appended after that.

### Running locally

```bash theme={null}
npm run sync-rest -- -s rest-api-description -o webhooks
```

Or use the dedicated script alias:

```bash theme={null}
npm run sync-webhooks
```

## GitHub Apps pipeline

The GitHub Apps pipeline generates the endpoint permission tables for:

* Endpoints available for GitHub App installation access tokens
* Endpoints available for GitHub App user access tokens
* Endpoints available for fine-grained personal access tokens
* Permissions required for GitHub Apps
* Permissions required for fine-grained personal access tokens

### Directory structure

```
src/github-apps/
├── components/    # React components for endpoint/permission tables
├── data/          # Auto-generated JSON files (do not edit manually)
├── lib/
│   └── config.json  # SHA of last synced rest-api-description commit
├── pages/         # Next.js page files
├── scripts/       # Pipeline scripts
└── tests/         # Vitest tests
```

### Running locally

```bash theme={null}
npm run sync-rest -- -s rest-api-description -o github-apps
```

### Content team guidance

Writers can update frontmatter and add an introduction paragraph in the associated Markdown file above the auto-generation comment:

```markdown theme={null}
<!-- Content after this section is automatically generated -->
```

The `versions` frontmatter property is overwritten on every pipeline run.

## Other automated documentation pipelines

Several other doc types are generated by independent sync scripts with their own workflows.

<AccordionGroup>
  <Accordion title="Audit logs — npm run sync-audit-log">
    **Workflow**: `.github/workflows/sync-audit-logs.yml`

    **Script**: `src/audit-logs/scripts/sync.ts`

    Generates audit log event documentation. Run manually with:

    ```bash theme={null}
    npm run sync-audit-log
    ```
  </Accordion>

  <Accordion title="Secret scanning — npm run sync-secret-scanning">
    **Workflow**: `.github/workflows/sync-secret-scanning.yml`

    **Script**: `src/secret-scanning/scripts/sync.ts`

    Generates the list of supported secret scanning patterns. Run manually with:

    ```bash theme={null}
    npm run sync-secret-scanning
    ```
  </Accordion>

  <Accordion title="CodeQL CLI — npm run sync-codeql-cli">
    **Workflow**: `.github/workflows/sync-codeql-cli.yml`

    **Script**: `src/codeql-cli/scripts/sync.ts`

    Generates CodeQL CLI reference documentation. Run manually with:

    ```bash theme={null}
    npm run sync-codeql-cli
    ```
  </Accordion>

  <Accordion title="GraphQL — npm run sync-graphql">
    **Workflow**: `.github/workflows/sync-graphql.yml`

    **Script**: `src/graphql/scripts/sync.ts`

    Fetches the GraphQL schema from GitHub's API. See [GraphQL docs](/engineering/graphql-docs) for details.
  </Accordion>
</AccordionGroup>

## SHA tracking

Each OpenAPI-driven pipeline stores the SHA of the `github/rest-api-description` commit it last synced from. This is recorded in the `sha` field of each pipeline's `config.json`:

* `src/webhooks/lib/config.json`
* `src/github-apps/lib/config.json`
* `src/rest/lib/config.json`

This value is updated automatically when the pipeline runs and gives you a precise reference for the source of every generated file.

## Escalation paths

| Issue                            | Contact                        |
| -------------------------------- | ------------------------------ |
| Pipeline failures                | `#docs-engineering` Slack      |
| OpenAPI schema errors            | `#api-platform` Slack          |
| Audit log / secret scanning data | Respective owning teams        |
| General questions                | `github/docs-engineering` repo |

## Known limitations

* **Shared pipeline** — Webhooks and GitHub Apps cannot be synced independently of each other or of REST. All three run together.
* **Single webhook page** — All webhook events render on a single page, which can affect performance for large payloads.
* **Introduction placement** — Writer-authored introductions must appear before automated content in the source Markdown file.