octokit / webhooks

machine-readable, always up-to-date GitHub Webhooks specifications

Octokit Webhooks

machine-readable, always up-to-date GitHub Webhooks specifications

Download

Download the latest specification at octokit.github.io/webhooks/payload-examples/api.github.com/index.json

Example

Example webhook definition

{
  "name": "issues",
  "actions": [
    "opened",
    "edited",
    "deleted",
    "transferred",
    "closed",
    "reopened",
    "assigned",
    "unassigned",
    "labeled",
    "unlabeled",
    "milestoned",
    "demilestoned"
  ],
  "examples": [
    {
      "action": "edited",
      "issue": {
        "url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2",
        "repository_url": "https://api.github.com/repos/Codertocat/Hello-World",
        "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/labels{/name}",
        "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/comments",
        "events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/events",
        "html_url": "https://github.com/Codertocat/Hello-World/issues/2",
        "id": 327883527,
        "node_id": "MDU6SXNzdWUzMjc4ODM1Mjc=",
        "number": 2,
        "title": "Spelling error in the README file",
        "user": {
          "login": "Codertocat",
          "id": 21031067,
          "node_id": "MDQ6VXNlcjIxMDMxMDY3",
          "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
          "gravatar_id": "",
          "url": "https://api.github.com/users/Codertocat",
          "html_url": "https://github.com/Codertocat",
          "followers_url": "https://api.github.com/users/Codertocat/followers",
          "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
          "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
          "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
          "organizations_url": "https://api.github.com/users/Codertocat/orgs",
          "repos_url": "https://api.github.com/users/Codertocat/repos",
          "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
          "received_events_url": "https://api.github.com/users/Codertocat/received_events",
          "type": "User",
          "site_admin": false
        },
        "labels": [
          {
            "id": 949737505,
            "node_id": "MDU6TGFiZWw5NDk3Mzc1MDU=",
            "url": "https://api.github.com/repos/Codertocat/Hello-World/labels/bug",
            "name": "bug",
            "color": "d73a4a",
            "default": true
          }
        ],
        "state": "open",
        "locked": false,
        "assignee": null,
        "assignees": [
          {
            "login": "Codertocat",
            "id": 21031067,
            "node_id": "MDQ6VXNlcjIxMDMxMDY3",
            "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
            "gravatar_id": "",
            "url": "https://api.github.com/users/Codertocat",
            "html_url": "https://github.com/Codertocat",
            "followers_url": "https://api.github.com/users/Codertocat/followers",
            "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
            "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
            "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
            "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
            "organizations_url": "https://api.github.com/users/Codertocat/orgs",
            "repos_url": "https://api.github.com/users/Codertocat/repos",
            "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
            "received_events_url": "https://api.github.com/users/Codertocat/received_events",
            "type": "User",
            "site_admin": false
          }
        ],
        "milestone": null,
        "comments": 0,
        "created_at": "2018-05-30T20:18:32Z",
        "updated_at": "2018-05-30T20:18:32Z",
        "closed_at": null,
        "author_association": "OWNER",
        "body": "It looks like you accidently spelled 'commit' with two 't's."
      },
      "changes": {},
      "repository": {
        "id": 135493233,
        "node_id": "MDEwOlJlcG9zaXRvcnkxMzU0OTMyMzM=",
        "name": "Hello-World",
        "full_name": "Codertocat/Hello-World",
        "owner": {
          "login": "Codertocat",
          "id": 21031067,
          "node_id": "MDQ6VXNlcjIxMDMxMDY3",
          "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
          "gravatar_id": "",
          "url": "https://api.github.com/users/Codertocat",
          "html_url": "https://github.com/Codertocat",
          "followers_url": "https://api.github.com/users/Codertocat/followers",
          "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
          "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
          "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
          "organizations_url": "https://api.github.com/users/Codertocat/orgs",
          "repos_url": "https://api.github.com/users/Codertocat/repos",
          "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
          "received_events_url": "https://api.github.com/users/Codertocat/received_events",
          "type": "User",
          "site_admin": false
        },
        "private": false,
        "html_url": "https://github.com/Codertocat/Hello-World",
        "description": null,
        "fork": false,
        "url": "https://api.github.com/repos/Codertocat/Hello-World",
        "forks_url": "https://api.github.com/repos/Codertocat/Hello-World/forks",
        "keys_url": "https://api.github.com/repos/Codertocat/Hello-World/keys{/key_id}",
        "collaborators_url": "https://api.github.com/repos/Codertocat/Hello-World/collaborators{/collaborator}",
        "teams_url": "https://api.github.com/repos/Codertocat/Hello-World/teams",
        "hooks_url": "https://api.github.com/repos/Codertocat/Hello-World/hooks",
        "issue_events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/events{/number}",
        "events_url": "https://api.github.com/repos/Codertocat/Hello-World/events",
        "assignees_url": "https://api.github.com/repos/Codertocat/Hello-World/assignees{/user}",
        "branches_url": "https://api.github.com/repos/Codertocat/Hello-World/branches{/branch}",
        "tags_url": "https://api.github.com/repos/Codertocat/Hello-World/tags",
        "blobs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/blobs{/sha}",
        "git_tags_url": "https://api.github.com/repos/Codertocat/Hello-World/git/tags{/sha}",
        "git_refs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/refs{/sha}",
        "trees_url": "https://api.github.com/repos/Codertocat/Hello-World/git/trees{/sha}",
        "statuses_url": "https://api.github.com/repos/Codertocat/Hello-World/statuses/{sha}",
        "languages_url": "https://api.github.com/repos/Codertocat/Hello-World/languages",
        "stargazers_url": "https://api.github.com/repos/Codertocat/Hello-World/stargazers",
        "contributors_url": "https://api.github.com/repos/Codertocat/Hello-World/contributors",
        "subscribers_url": "https://api.github.com/repos/Codertocat/Hello-World/subscribers",
        "subscription_url": "https://api.github.com/repos/Codertocat/Hello-World/subscription",
        "commits_url": "https://api.github.com/repos/Codertocat/Hello-World/commits{/sha}",
        "git_commits_url": "https://api.github.com/repos/Codertocat/Hello-World/git/commits{/sha}",
        "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/comments{/number}",
        "issue_comment_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/comments{/number}",
        "contents_url": "https://api.github.com/repos/Codertocat/Hello-World/contents/{+path}",
        "compare_url": "https://api.github.com/repos/Codertocat/Hello-World/compare/{base}...{head}",
        "merges_url": "https://api.github.com/repos/Codertocat/Hello-World/merges",
        "archive_url": "https://api.github.com/repos/Codertocat/Hello-World/{archive_format}{/ref}",
        "downloads_url": "https://api.github.com/repos/Codertocat/Hello-World/downloads",
        "issues_url": "https://api.github.com/repos/Codertocat/Hello-World/issues{/number}",
        "pulls_url": "https://api.github.com/repos/Codertocat/Hello-World/pulls{/number}",
        "milestones_url": "https://api.github.com/repos/Codertocat/Hello-World/milestones{/number}",
        "notifications_url": "https://api.github.com/repos/Codertocat/Hello-World/notifications{?since,all,participating}",
        "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/labels{/name}",
        "releases_url": "https://api.github.com/repos/Codertocat/Hello-World/releases{/id}",
        "deployments_url": "https://api.github.com/repos/Codertocat/Hello-World/deployments",
        "created_at": "2018-05-30T20:18:04Z",
        "updated_at": "2018-05-30T20:18:10Z",
        "pushed_at": "2018-05-30T20:18:30Z",
        "git_url": "git://github.com/Codertocat/Hello-World.git",
        "ssh_url": "[email protected]:Codertocat/Hello-World.git",
        "clone_url": "https://github.com/Codertocat/Hello-World.git",
        "svn_url": "https://github.com/Codertocat/Hello-World",
        "homepage": null,
        "size": 0,
        "stargazers_count": 0,
        "watchers_count": 0,
        "language": null,
        "has_issues": true,
        "has_projects": true,
        "has_downloads": true,
        "has_wiki": true,
        "has_pages": true,
        "forks_count": 0,
        "mirror_url": null,
        "archived": false,
        "open_issues_count": 2,
        "license": null,
        "forks": 0,
        "open_issues": 2,
        "watchers": 0,
        "default_branch": "master"
      },
      "sender": {
        "login": "Codertocat",
        "id": 21031067,
        "node_id": "MDQ6VXNlcjIxMDMxMDY3",
        "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/Codertocat",
        "html_url": "https://github.com/Codertocat",
        "followers_url": "https://api.github.com/users/Codertocat/followers",
        "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
        "organizations_url": "https://api.github.com/users/Codertocat/orgs",
        "repos_url": "https://api.github.com/users/Codertocat/repos",
        "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/Codertocat/received_events",
        "type": "User",
        "site_admin": false
      }
    }
  ]
}

Download webhook definitions and webhook payloads schema

You can download the latest index.json and schema.json files from unpkg

• index.json
• schema.json

Usage as Node module

To get an array of all webhook definition objects, require the @octokit/webhooks-examples package.

// Use Node.js require:
const WEBHOOKS = require("@octokit/webhooks-examples/api.github.com/index.json");

// Or ESM/TypeScript import:
import WEBHOOKS from "@octokit/webhooks-examples/api.github.com/index.json";

To get the JSON schema for webhook payloads, require the @octokit/webhooks-schemas package.

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

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

Usage with ajv in strict mode

When running in strict mode, ajv will throw an "unknown keyword" error if it encounters any keywords that have not been defined.

This schema currently uses custom keywords provided by ajv-formats, along with the custom keyword tsAdditionalProperties.

Here is an example of how you can set this up:

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);
ajv.addKeyword("tsAdditionalProperties");

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

Importing types

This package ships with types for the webhook events generated from the respective json schemas, which you can use like so:

import { WebhookEvent, IssuesOpenedEvent } from "@octokit/webhooks-types";

const handleWebhookEvent = (event: WebhookEvent) => {
  if ("action" in event && event.action === "completed") {
    console.log(`${event.sender.login} completed something!`);
  }
};

const handleIssuesOpenedEvent = (event: IssuesOpenedEvent) => {
  console.log(
    `${event.sender.login} opened "${event.issue.title}" on ${event.repository.full_name}`,
  );
};

⚠️ Caution ⚠️: Webhooks Types are expected to be used with the strictNullChecks option enabled in your tsconfig. If you don't have this option enabled, there's the possibility that you get never as the inferred type in some use cases. See #395 for details.

How it works

This package updates itself using a daily cronjob running on GitHub Actions. The index.json file is generated by bin/octokit-webhooks.mts. Run npm run octokit-webhooks -- --usage for instructions. After the update is complete, run npm run build:webhooks and npm run build:schema to update index.json and schema.json files.

The update script is scraping GitHub’s Webhooks Event Types & Payloads documentation page and extracts the meta information using cheerio.

For simpler local testing and tracking of changes all loaded pages are cached in the cache/ folder.

See also

• octokit/graphql-schema – GitHub’s GraphQL Schema with validation
• octokit/openapi – GitHub REST API route specifications
• octokit/app-permissions – GitHub App permission specifications

JSON Schema conventions

What conventions are the schemas of this repository following?

This section offers the origin of these conventions and the reasoning behind them.

"email" for committer.schema.json treated as a regular string

The JSON schema for a committer (committer.schema.json) has a property "email", which originally was using the default email format offered by ajv-format.

What we noticed is the Regular Expression used by ajv-format for emails is not accepting emails containing [ or ] characters (i.e. 41898282+github-actions[bot]@users.noreply.github.com).

After considering the option of applying our pattern by extending ajv-format Regular Expression for emails, we considered not to do that because:

• It is an excellent way to cause more trouble (the size of this Regular Expression alone is enormous even before you think about all the sub-patterns).
• The moment we decide to use our Regular Expression, we are committing to maintaining it, so if someone else comes along and presents another email that is considered invalid by this pattern but works with git, we will need to safely modify the pattern again to cover that in addition to what we currently consider valid.
• If we want to be accurate, we should follow a spec to decide what is valid and what is not. Since GitHub is not following a spec for emails (and it will not change any time soon), to be validating emails with our RegEx would not be correct either.

You can read more details and the discussion behind in this resources:

• #453
• #677
• #678

LICENSE

MIT

webhooks's Issues

The `content_url` property is not available in `project_card`

The object WebhookPayloadProjectCardProjectCard does not contain a property for content_url so it's not possible to identify which issue is referenced by the project card.

It seems that the information is not available in the Webhooks project, I think it's because the moved card schema is not including it and it's not allowing extra properties.

Use GitHub's OpenAPI spec as source of truth for generating schemas

The openapi spec for the rest api shares a lot of properties with these shemas.
Later on, we could try and use it as the source of truth where possible.

Originally posted by @wolfy1339 in #264 (comment)

Programatically PR new common Schemas

Still have to take a look into @G-Rath scripts but, would have sense to run those scripts programmatically and open a PR for each common schema change proposal instead of spotting them during our developments?

Has sense what I'm asking? Would it be feasible? @G-Rath @wolfy1339

---

Are you proposing creating a new common schema?

That's fine with me - I've got two scripts for doing that: extract-common-schema & ref-common-schemas.

The first takes a path to a property on an interface and the name you want to give the interface for that common interface, and figures out how to extract the schema.

The second then goes through all the schemas and compared each property + value to all our common schemas, replacing any that match with references to the matching schema.

So in this case, you'd run bin/extract-common-schema IssueCommentCreated.issue issue to extract the schema, and then bin/ref-common-schemas to replace all objects that match the newly created schema with a reference :)

There are tons of common schemas to be extracted - pretty much every event has at least one common schema, since we're got a schema per action (i.e "issue" events will have an issue property, pull_request events all have a pull_request property, milestones all have a milestone property, etc) so feel free to go nuts!

Originally posted by @G-Rath in #312 (comment)

create tests

We're going to be introducing some changes to this module soon, namely adding GHE support in #25

Before we do that, let's add some basic to tests for the exported module object, to ensure that we don't accidentally break it with any future updates.

To check "Dismiss stale pull request approvals when new commits are pushed"

What’s missing?
To check "Dismiss stale pull request approvals when new commits are pushed" (https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule#creating-a-branch-protection-rule)

Why?
To require review of a PR if it has changed since last approval.
Example: #317

Dependency Dashboard

This issue contains a list of Renovate updates and their statuses.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• build(deps): lock file maintenance

---

• Check this box to trigger a request for Renovate to run again on this repository

Add automatic schema updating

What’s missing?

Automatic schema updating whenever a payload doesn't match the schema

Why?

Currently, we are manually checking each webhook sent, and checking the details of why it failed validation and editing the appropriate schemas with the changes needed to make the validation pass.

Alternatives you tried

N/A

It will be a lot of hard work, but I think it will pay off

obsolete events

• download: https://developer.github.com/v3/activity/events/types/#downloadevent
• follow: https://developer.github.com/v3/activity/events/types/#followevent
• fork_apply: https://developer.github.com/v3/activity/events/types/#forkapplyevent
• gist: https://developer.github.com/v3/activity/events/types/#gistevent

Missing example payloads without installation key for multiple events

Multiple event payload examples, contain the installation key while not having an example without that key.

Ex. pull_request.closed had no example payload that didn't contain the installation key, and such the generated schemas for that event in #186 are wrong.

add ISSUE_TEMPLATES to repository

Missing `check_suite_id` property of `WorkflowRun` interface in schema

workflowrun has check_suite_url but in the paylod there is also check_suite_id

webhooks/schema.d.ts

Line 4927 in c7f0d67

check_suite_url: string;

Include webhook event descriptions

Followup from octokit/webhooks.js#86, it'd be really cool to include webhook event descriptions:

So the block of text below OrgBlockEvent in this example. Those can vary pretty widely, here's a different example of the same text:

---

Why:

I'd love to use this to build automatic documentation for specific features of my application, and for something where you can choose an event it'd be great to share this context there. Certainly not a deal-breaker, but might be nice to have!

Schema is missing payload contents

In the generated schema there is only name, actions, and examples. The payload of the webhook is not pulled from the documentation. This results in major consequences down the chain as webhooks.js is derived from this, as is all the TypeScript typings for the webhooks.

This means that critical payload values that exist in the webhook are not accessible in TypeScript without some terrible escape hatches.

For example, in an IssuesEvent, a developer trying to access the label payload property would not get prompted that it exists:

And entering it anyway results in a compiler error, even though the property exists in the webhook:

The only workaround I've found is to override the types to add the missing properties when they are needed, or escape hatch with any:

webhooks.on('issues.labeled', ({payload}: {payload: any}) => {
  const label = payload.label
})

Since using any removes any type checking, it kinda defeats the purpose of having a schema. So it would be great if the schema could be complete enough to include all the payload parameters in the documentation.

Thanks!

WebHookPayloadPullRequest.installation is missing from typings

From: octokit/webhooks.js#176

Add URL of documentation on docs.github.com/webhooks

It would be useful for when generating docs such as https://github.com/octokit/webhooks.js#webhook-events. Not all events are listed on https://developer.github.com/v3/activity/events/types/#checkrunevent, ping and repository_dispatch are documented in other places

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Cannot push to the Git repository.

semantic-release cannot push the version tag to the branch master on the remote Git repository with URL https://x-access-token:[secure]@github.com/octokit/webhooks.

This can be caused by:

• a misconfiguration of the repositoryUrl option
• the repository being unavailable
• or missing push permission for the user configured via the Git credentials on your CI environment

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Missing / wrong actions

• created action is missing for commit_comment event, it is not listed in the Events API payload table
• added, deleted and edited actions are missing for member event, the actions are listed in the Events API payload table but not the first row where the script is currently expecting it
• created and deleted actions are missing for installlation event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• added and removed actions are missing for installation_repositories event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• created, deleted and edited actions are missing for issue_comment event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• created, deleted and edited actions are missing for label event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• added, removed actions are missing for membership event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• closed, created, deleted, edited and reopened actions are missing for project event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• converted , created, deleted, edited and moved actions are missing for project_card event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• created, deleted, edited and moved actions are missing for project_column event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• assigned, closed, edited, labeled, opened, reopened, review_request_removed, review_requested, synchronize, unassigned, and unlabeled actions are missing for pull_request event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• merged and false actions are incorrectly listed as actions for pull_request event, due to how the current script is looking for the event names in the actions description
• dismissed, edited and submitted actions are missing for pull_request_review event, the actions are listed in the Events API payload table but not formatted as expected by the current script
• published action is missing for release event, the action is listed in the Events API payload table but not formatted as expected by the current script

🐛 Bug: Wrong folder name for ISSUE_TEMPLATEs

What happened?
When trying to create a new issue, the issue template selector is not appearing

What did you expect to happen?
To be able to select an Issue Template

What the problem might be
.github/ISSUE_TEMPLATES/ ➡️ .github/ISSUE_TEMPLATE/

An in-range update of yargs is breaking the build 🚨

The devDependency yargs was updated from 13.2.2 to 13.2.4.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

yargs is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ Travis CI - Branch: The build errored.

---

Commits

The new version differs by 14 commits.

• a6e67f1 chore(release): 13.2.4
• fc13476 chore: update standard-verison dependency
• bf46813 fix(i18n): rename unclear 'implication failed' to 'missing dependent arguments' (#1317)
• a3a5d05 docs: fix a broken link to MS Terminology Search (#1341)
• b4f8018 build: add .versionrc that hides test/build
• 0c39183 chore(release): 13.2.3
• 08e0746 chore: update deps (#1340)
• 843e939 docs: make --no- boolean prefix easier to find in the docs (#1338)
• 84cac07 docs: restore removed changelog of v13.2.0 (#1337)
• b20db65 fix(deps): upgrade cliui for compatibility with latest chalk. (#1330)
• c294d1b test: accept differently formatted output (#1327)
• ac3f10c chore: move .hbs templates into .js to facilitate webpacking (#1320)
• 0295132 fix: address issues with dutch translation (#1316)
• 9f2468e doc: clarify parserConfiguration object structure (#1309)

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Migrate @octokit/webhooks-definitions to Typescript

Create a JSON Schema for webhook events

Following the discussion in octokit/webhooks.js#171 the plan is to manually create a JSON Schema of webhook events.

As a first step I will bootstrap the schema by feeding the examples through some generator tool (I have my eyes on https://jsonschema.net/ now, but I haven't tried it yet). The second step would take manually correcting the definitions and converting them to enums as needed.

And finally, it would be nice to use the freshly-available schema to generate TypeScript definitions in octokit/webhooks.js using bcherny/json-schema-to-typescript.

Please document `on: schedule` event payload

From what I see the schedule event contains just a single field with the schedule itself, however, it is not documented.

PullRequestOpenedEvent.pull_request is never

What happened?

What did you expect to happen?

non-never

What the problem might be

"synchronize" action is missing for "pull_request"

To start scraping docs.github.com

https://developer.github.com/webhooks/event-payloads/ is no more

We must update our scraper to get its data from https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads instead.

Originally posted by @gr2m in #124 (comment)

"ping" event is missing

See https://developer.github.com/webhooks/#ping-event, it is currently not listed on https://developer.github.com/v3/activity/events/types

Wrong installation_repositories type definition

octokit/webhooks.js#59

  type WebhookPayloadInstallationRepositories =
-    | Array<WebhookPayloadInstallationRepositoriesItem>
-    | {
+      {
        action: string;
        installation: WebhookPayloadInstallationRepositoriesInstallation;
        repository_selection: string;
-       repositories_added: Array<any>;
+       repositories_added: Array<WebhookPayloadInstallationRepositoriesRepositoriesAddedItem>;
        repositories_removed: Array<WebhookPayloadInstallationRepositoriesRepositoriesRemovedItem>;
        sender: WebhookPayloadInstallationRepositoriesSender;
      };

Removal of `integration_installation_repositories`

Should we remove integration_installation_repositories since it's deprecated and no longer sent since October 2020?

Missing examples of code_scanning_alert payloads with "sender"

According to the docs, when the action is reopened_by_user or closed_by_user, the payload for code_scanning_alert will have a sender property.

Since there are no examples of these actions, the types generated in webhooks.js doesn't have sender at all.

I'm not familiar enough with code scanning to generate these events to capture their payloads, but if I do capture one I'll PR it :)

scrape payloads from Github API documentation

Context

There are some examples of payloads on Github API Docs which are not matching (missing fields mostly) with the table and the real payload delivered by Github Events, so the script used in this repo to update the definitions is not covering all of the cases.

Issues related to this topic:
#43
octokit/webhooks.js#87
octokit/webhooks.js#94

Proposal

As pointed by @gr2m here it would be nice to scrape the tables with each property and generate definitions from there since it seems that payloads examples are not updated with the latest changes on GitHub's

---

Let's open the discussion and clarify how to tackle it and start the development! 💪

RepositoryDispatch event is missing

See https://developer.github.com/actions/creating-workflows/triggering-a-repositorydispatch-webhook/

This one is special, because the actions are user-defined, so I’m not sure how we would add it to our definitions, maybe with a new flag like .hasCustomActions

Typescript IssueCommentEvent.issue type is never

Trying to use type IssueCommentEvent accessing issue property yields never type:

import('@octokit/webhooks-definitions/schema').IssueCommentEvent['issue']

I would expect it to have some type, either Issue or some augmentation of it

Perhaps there's some conflict between the Issue type and specific type overwriting it it

An in-range update of semantic-release is breaking the build 🚨

The devDependency semantic-release was updated from 15.13.26 to 15.13.27.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

semantic-release is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ Travis CI - Branch: The build errored.

---

Release Notes for v15.13.27

15.13.27 (2019-10-18)

Bug Fixes

• ignore custom port when converting ssh repo URL to https (4af8548)

Commits

The new version differs by 3 commits.

• 3438ec5 test: fix typo in test examples
• 4af8548 fix: ignore custom port when converting ssh repo URL to https
• dc19dfa docs: remove unnecessarily apostrophe

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

extract event descriptions

Let's update the section-to-webhook to also extract webhook descriptions.

Example: https://developer.github.com/v3/activity/events/types/#checksuiteevent

"content_reference" event is missing

I left this one out on purpose to check the nightly cron job setup. If everything works out as planned, then travis & our octokitbot should create a pull request tonight adding the content_reference event.

scrape and export GitHub Enterprise versions of webhooks

https://developer.github.com/enterprise/<GHE version>/v3/activity/events/types/,
e.g. https://developer.github.com/enterprise/2.16/v3/activity/events/types/

`installation.created` webhook event payload has incorrect type

What happened?

The installation.created webhook event payload type is incorrect.

What did you expect to happen?

I expected the requester property to be of type User | undefined. Instead, it is declared as type null | undefined.

What the problem might be

The Github API documentation also doesn't acknowledge this property's existence. Also cross posted to octokit/webhooks.js#520 (where I was advised to post an issue in this repo as well).

Example Payload

{
   "action":"created",
   "installation":{
      "id":15819815,
      "account":{
         "login":"instantish-dev",
         "id":71402524,
         "node_id":"MDEyOk9yZ2FuaXphdGlvbjcxNDAyNTI0",
         "avatar_url":"https://avatars.githubusercontent.com/u/71402524?v=4",
         "gravatar_id":"",
         "url":"https://api.github.com/users/instantish-dev",
         "html_url":"https://github.com/instantish-dev",
         "followers_url":"https://api.github.com/users/instantish-dev/followers",
         "following_url":"https://api.github.com/users/instantish-dev/following{/other_user}",
         "gists_url":"https://api.github.com/users/instantish-dev/gists{/gist_id}",
         "starred_url":"https://api.github.com/users/instantish-dev/starred{/owner}{/repo}",
         "subscriptions_url":"https://api.github.com/users/instantish-dev/subscriptions",
         "organizations_url":"https://api.github.com/users/instantish-dev/orgs",
         "repos_url":"https://api.github.com/users/instantish-dev/repos",
         "events_url":"https://api.github.com/users/instantish-dev/events{/privacy}",
         "received_events_url":"https://api.github.com/users/instantish-dev/received_events",
         "type":"Organization",
         "site_admin":false
      },
      "repository_selection":"all",
      "access_tokens_url":"https://api.github.com/app/installations/15819815/access_tokens",
      "repositories_url":"https://api.github.com/installation/repositories",
      "html_url":"https://github.com/organizations/instantish-dev/settings/installations/15819815",
      "app_id":81168,
      "app_slug":"instantish-github-app-dev",
      "target_id":71402524,
      "target_type":"Organization",
      "permissions":{
         "issues":"write",
         "members":"read",
         "metadata":"read",
         "single_file":"write",
         "pull_requests":"write",
         "repository_projects":"write",
         "organization_projects":"write"
      },
      "events":[
         "issues",
         "issue_comment",
         "label",
         "member",
         "membership",
         "milestone",
         "organization",
         "project",
         "project_card",
         "pull_request",
         "repository"
      ],
      "created_at":"2021-03-30T00:50:20.000-04:00",
      "updated_at":"2021-03-30T00:50:20.000-04:00",
      "single_file_name":".github/ISSUE_TEMPLATE/adr.md",
      "has_multiple_single_files":true,
      "single_file_paths":[
         ".github/ISSUE_TEMPLATE/adr.md",
         ".github/ISSUE_TEMPLATE/bug_report.md"
      ],
      "suspended_by":null,
      "suspended_at":null
   },
   "repositories":[
      {
         "id":332330061,
         "node_id":"MDEwOlJlcG9zaXRvcnkzMzIzMzAwNjE=",
         "name":"test-23",
         "full_name":"instantish-dev/test-23",
         "private":false
      },
      {
         "id":333493655,
         "node_id":"MDEwOlJlcG9zaXRvcnkzMzM0OTM2NTU=",
         "name":"test-27",
         "full_name":"instantish-dev/test-27",
         "private":false
      },
      {
         "id":345480138,
         "node_id":"MDEwOlJlcG9zaXRvcnkzNDU0ODAxMzg=",
         "name":"private-repo",
         "full_name":"instantish-dev/private-repo",
         "private":true
      }
   ],
   "requester":{
      "login":"richard-instantish-test-account-2",
      "id":74567412,
      "node_id":"MDQ6VXNlcjc0NTY3NDEy",
      "avatar_url":"https://avatars.githubusercontent.com/u/74567412?v=4",
      "gravatar_id":"",
      "url":"https://api.github.com/users/richard-instantish-test-account-2",
      "html_url":"https://github.com/richard-instantish-test-account-2",
      "followers_url":"https://api.github.com/users/richard-instantish-test-account-2/followers",
      "following_url":"https://api.github.com/users/richard-instantish-test-account-2/following{/other_user}",
      "gists_url":"https://api.github.com/users/richard-instantish-test-account-2/gists{/gist_id}",
      "starred_url":"https://api.github.com/users/richard-instantish-test-account-2/starred{/owner}{/repo}",
      "subscriptions_url":"https://api.github.com/users/richard-instantish-test-account-2/subscriptions",
      "organizations_url":"https://api.github.com/users/richard-instantish-test-account-2/orgs",
      "repos_url":"https://api.github.com/users/richard-instantish-test-account-2/repos",
      "events_url":"https://api.github.com/users/richard-instantish-test-account-2/events{/privacy}",
      "received_events_url":"https://api.github.com/users/richard-instantish-test-account-2/received_events",
      "type":"User",
      "site_admin":false
   },
   "sender":{
      "login":"rr-codes",
      "id":16073505,
      "node_id":"MDQ6VXNlcjE2MDczNTA1",
      "avatar_url":"https://avatars.githubusercontent.com/u/16073505?v=4",
      "gravatar_id":"",
      "url":"https://api.github.com/users/rr-codes",
      "html_url":"https://github.com/rr-codes",
      "followers_url":"https://api.github.com/users/rr-codes/followers",
      "following_url":"https://api.github.com/users/rr-codes/following{/other_user}",
      "gists_url":"https://api.github.com/users/rr-codes/gists{/gist_id}",
      "starred_url":"https://api.github.com/users/rr-codes/starred{/owner}{/repo}",
      "subscriptions_url":"https://api.github.com/users/rr-codes/subscriptions",
      "organizations_url":"https://api.github.com/users/rr-codes/orgs",
      "repos_url":"https://api.github.com/users/rr-codes/repos",
      "events_url":"https://api.github.com/users/rr-codes/events{/privacy}",
      "received_events_url":"https://api.github.com/users/rr-codes/received_events",
      "type":"User",
      "site_admin":false
   }
}

Replace "debug" with "log" constructor option

We don't use the debug package in any other Octokit module. Instead we use a console-compatible log API, and users can pass their own log object, see https://github.com/octokit/core.js#logging

More info here: octokit/webhooks.js#186

False-positives for missing schemas when an error occurs during schema validation

What happened?

Running node bin/validate-payload-examples.js with a typo in the path to a common schema throws an error that is then falsely logged as missing schema

What did you expect to happen?

For the logged error message to match the actual error thrown in the code

What the problem might be
Instead of sending an error message related to the actual error, we swallow the error that was thrown and falsely assume it means that the schema does not exist

https://github.com/octokit/webhooks/blob/master/bin/validate-payload-examples.js#L24-L26

remove leftover references to Travis CI

This project used to use Travis CI cron, but now uses GitHub Actions. There are some leftover references to Travis in the docs that should be updated.

WorkflowRun interface conclusion non null values to be typed

https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#workflow_run

workflow_run | object | The workflow run. Many workflow_run keys, such as head_branch, conclusion, and pull_requests are the same as those in a check_suite object.

check_suite[conclusion] | string | The summary conclusion for all check runs that are part of the check suite. Can be one of success, failure, neutral, cancelled, timed_out, action_required or stale. This value will be null until the check run has completed.

Currently

webhooks/schema.d.ts

Line 243 in 6d075cf

export type WorkflowRunEvent =

export type WorkflowRunEvent =
  | WorkflowRunCompletedEvent
  | WorkflowRunRequestedEvent;

export interface WorkflowRunCompletedEvent {
  action: "completed";
  organization?: Organization;
  repository: Repository;
  sender: User;
  workflow: Workflow;
  workflow_run: WorkflowRun;
  installation?: InstallationLite;
}
export interface WorkflowRunRequestedEvent {
  action: "requested";
  organization?: Organization;
  repository: Repository;
  sender: User;
  workflow: Workflow;
  workflow_run: WorkflowRun;
  installation?: InstallationLite;
}
export interface WorkflowRun {
  ...
  conclusion: string | null;

I think that there may need to be a Conclusion type enum / union ( no null ) and for there to be separate WorkflowRunCompleted ( conclusion : Conclusion ) WorkflowRunRequested ( conclusion : null ) with a common base interface.

I expect that this applies equally to CheckSuiteRequestedEvent ( null

webhooks/payload-examples/api.github.com/check_suite/requested.payload.json

Line 9 in 6d075cf

"conclusion": null,

) and CheckSuiteRerequestedEvent/CheckSuiteRequestedEvent

Problems with "extending" schemas in generated types

I stumbled onto this while working on resolving octokit/app.js#212
This should be easily reproduced, just use the type as one would normally do and TypeScript will reduce the type to never

Property 'number' does not exist on type 'never'.
  The intersection 'Issue & { state: "open"; closed_at: null; }' was reduced to 'never' because property 'closed_at' has conflicting types in some constituents.ts(2339)

Missing payload examples

Payload examples

• code_scanning_alert.appeared_in_branch
• code_scanning_alert.closed_by_user
• code_scanning_alert.created
• code_scanning_alert.fixed
• code_scanning_alert.reopened_by_user
• deploy_key.deleted
• deployment.created
• deployment_status.created
• installation.suspend
• installation.unsuspend
• #577
• issues.deleted
• issues.reopened
• issues.transferred
• issues.unpinned
• marketplace_purchase.pending_change
• marketplace_purchase.pending_change_cancelled
• member.removed
• milestone.edited
• milestone.opened
• organization.deleted
• organization.member_invited
• organization.member_removed
• organization.renamed
• package.updated
• project.closed
• project.deleted
• project.edited
• project.reopened
• project_card.converted
• project_card.edited
• project_card.moved
• project_column.deleted
• project_column.edited
• project_column.moved
• pull_request.edited
• pull_request.review_request_removed
• pull_request.review_requested
• pull_request.synchronize
• pull_request_review.dismissed
• pull_request_review.edited
• pull_request#auto_merge_{enable, disable}
• release.deleted
• release.edited
• release.prereleased
• release.released
• release.unpublished
• repository.archived
• repository.deleted
• repository.renamed
• repository.unarchived
• repository_dispatch.on-demand-test
• repository_vulnerability_alert.resolve
• secret_scanning_alert.created
• secret_scanning_alert.resolved
• security_advisory.performed
• sponsorship.cancelled
• sponsorship.edited
• sponsorship.pending_cancellation
• sponsorship.pending_tier_change
• sponsorship.tier_changed
• branch_protection_configuration
• deployment_protection_rule
• installation_target
• personal_access_token_request
• projects_v2
• repository_advisory
• repository_ruleset
• secret_scanning_alert_location
• security_and_analysis

Refactor proposal: To `issue` property in issue schemas from a common schema

What’s missing?

From

issue_commented/created.schema.json

...
"issue": {
   ...
}
...

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "issue_comment$created",
  "type": "object",
  "required": ["action", "issue", "comment", "repository", "sender"],
  "properties": {
    "action": { "type": "string", "enum": ["created"] },
    "issue": {
      "type": "object",
      "required": [
        "url",
        "repository_url",
        "labels_url",
        "comments_url",
        "events_url",
        "html_url",
        "id",
        "node_id",
        "number",
        "title",
        "user",
        "labels",
        "state",
        "locked",
        "assignee",
        "assignees",
        "milestone",
        "comments",
        "created_at",
        "updated_at",
        "closed_at",
        "author_association",
        "active_lock_reason",
        "body"
      ],
      "properties": {
        "url": { "type": "string" },
        "repository_url": { "type": "string" },
        "labels_url": { "type": "string" },
        "comments_url": { "type": "string" },
        "events_url": { "type": "string" },
        "html_url": { "type": "string" },
        "id": { "type": "integer" },
        "node_id": { "type": "string" },
        "number": { "type": "integer" },
        "title": { "type": "string" },
        "user": { "$ref": "common/user.schema.json" },
        "labels": {
          "type": "array",
          "items": { "$ref": "common/label.schema.json" }
        },
        "state": { "type": "string", "enum": ["open", "closed"] },
        "locked": { "type": "boolean" },
        "assignee": {
          "oneOf": [{ "$ref": "common/user.schema.json" }, { "type": "null" }]
        },
        "assignees": {
          "type": "array",
          "items": { "$ref": "common/user.schema.json" }
        },
        "milestone": {
          "type": "object",
          "required": [
            "url",
            "html_url",
            "labels_url",
            "id",
            "node_id",
            "number",
            "title",
            "description",
            "creator",
            "open_issues",
            "closed_issues",
            "state",
            "created_at",
            "updated_at",
            "due_on",
            "closed_at"
          ],
          "properties": {
            "url": { "type": "string" },
            "html_url": { "type": "string" },
            "labels_url": { "type": "string" },
            "id": { "type": "integer" },
            "node_id": { "type": "string" },
            "number": { "type": "integer" },
            "title": { "type": "string" },
            "description": { "type": "string" },
            "creator": { "$ref": "common/user.schema.json" },
            "open_issues": { "type": "integer" },
            "closed_issues": { "type": "integer" },
            "state": { "type": "string" },
            "created_at": { "type": "string" },
            "updated_at": { "type": "string" },
            "due_on": { "type": "string" },
            "closed_at": { "type": "string" }
          },
          "additionalProperties": false
        },
        "comments": { "type": "integer" },
        "created_at": { "type": "string" },
        "updated_at": { "type": "string" },
        "closed_at": { "type": "null" },
        "author_association": {
          "type": "string",
          "enum": [
            "COLLABORATOR",
            "CONTRIBUTOR",
            "FIRST_TIMER",
            "FIRST_TIME_CONTRIBUTOR",
            "MANNEQUIN",
            "MEMBER",
            "NONE",
            "OWNER"
          ]
        },
        "active_lock_reason": {
          "type": ["string", "null"],
          "enum": ["resolved", "off-topic", "too heated", "spam", null]
        },
        "pull_request": {
          "type": "object",
          "required": ["url", "html_url", "diff_url", "patch_url"],
          "properties": {
            "url": { "type": "string" },
            "html_url": { "type": "string" },
            "diff_url": { "type": "string" },
            "patch_url": { "type": "string" }
          },
          "additionalProperties": false
        },
        "body": { "type": "string" },
        "performed_via_github_app": { "type": "null" }
      },
      "additionalProperties": false
    },
    "comment": {
      "type": "object",
      "required": [
        "url",
        "html_url",
        "issue_url",
        "id",
        "node_id",
        "user",
        "created_at",
        "updated_at",
        "author_association",
        "body"
      ],
      "properties": {
        "url": { "type": "string" },
        "html_url": { "type": "string" },
        "issue_url": { "type": "string" },
        "id": { "type": "integer" },
        "node_id": { "type": "string" },
        "user": { "$ref": "common/user.schema.json" },
        "created_at": { "type": "string" },
        "updated_at": { "type": "string" },
        "author_association": {
          "type": "string",
          "enum": [
            "COLLABORATOR",
            "CONTRIBUTOR",
            "FIRST_TIMER",
            "FIRST_TIME_CONTRIBUTOR",
            "MANNEQUIN",
            "MEMBER",
            "NONE",
            "OWNER"
          ]
        },
        "body": { "type": "string" }
      },
      "additionalProperties": false
    },
    "repository": { "$ref": "common/repository.schema.json" },
    "sender": { "$ref": "common/user.schema.json" },
    "installation": { "$ref": "common/installation.schema.json" },
    "organization": { "$ref": "common/organization.schema.json" }
  },
  "additionalProperties": false,
  "title": "issue_comment created event"
}

To

issue_commented/created.schema.json

...
"issue": { "$ref": "common/issue.schema.json" }
...

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "issue_comment$created",
  "type": "object",
  "required": ["action", "issue", "comment", "repository", "sender"],
  "properties": {
    "action": { "type": "string", "enum": ["created"] },
    "issue": { "$ref": "common/issue.schema.json" },
    "comment": {
      "type": "object",
      "required": [
        "url",
        "html_url",
        "issue_url",
        "id",
        "node_id",
        "user",
        "created_at",
        "updated_at",
        "author_association",
        "body"
      ],
      "properties": {
        "url": { "type": "string" },
        "html_url": { "type": "string" },
        "issue_url": { "type": "string" },
        "id": { "type": "integer" },
        "node_id": { "type": "string" },
        "user": { "$ref": "common/user.schema.json" },
        "created_at": { "type": "string" },
        "updated_at": { "type": "string" },
        "author_association": {
          "type": "string",
          "enum": [
            "COLLABORATOR",
            "CONTRIBUTOR",
            "FIRST_TIMER",
            "FIRST_TIME_CONTRIBUTOR",
            "MANNEQUIN",
            "MEMBER",
            "NONE",
            "OWNER"
          ]
        },
        "body": { "type": "string" }
      },
      "additionalProperties": false
    },
    "repository": { "$ref": "common/repository.schema.json" },
    "sender": { "$ref": "common/user.schema.json" },
    "installation": { "$ref": "common/installation.schema.json" },
    "organization": { "$ref": "common/organization.schema.json" }
  },
  "additionalProperties": false,
  "title": "issue_comment created event"
}

Why?
Centralize schema properties and avoid code repetition.

@wolfy1339 @G-Rath not sure if this would be correct. If you think has sense I would be happy to jump on this refactor so I get more hands on with this schemas task force.

Let me know your thoughts :)

Inspired by these changes e29e066

Add support for optional parameter `installation` for Webhook Payloads missing it

Context here: octokit/webhooks.js#266

Moving `index.json` to a different package

What’s missing?
Would be nice to not pack examples when publishing this package.

Why?
Avoid extra package size

Context: octokit/webhooks.js#439 (comment)

Only cache the HTML content of `#article-contents`

We get a lot of false positive Pull Request with cache updates that we don't care about.

The reason for that is that we cache the entire HTML response. What I would suggest we do instead is

1. Only cache the content of the #article-contents div (compare https://github.com/octokit/app-permissions/blob/28a98e3bd60e2588715270742822e765f73033b7/scripts/update.js#L20-L24)
2. Format the HTML before saving the cached HTML (compare https://github.com/octokit/app-permissions/blob/28a98e3bd60e2588715270742822e765f73033b7/scripts/update.js#L27)

Add comment description to "extract-common-schema" script

@G-Rath would you mind adding a few lines to the top of /bin/extract-common-schema.ts describing what the script does and how it works? No need to go into much detail, just to give a quick overview

Make RepositoryDispatchOnDemandTestEvent generic

webhooks/schema.d.ts

Line 215 in 6d075cf

export type RepositoryDispatchEvent = RepositoryDispatchOnDemandTestEvent;

export interface RepositoryDispatchOnDemandTestEvent {
  action: "on-demand-test";
  branch: string;
  client_payload: {
    [k: string]: unknown;
  };
  repository: Repository;
  sender: User;
  installation: InstallationLite;
  organization?: Organization;
}

change to

export interface RepositoryDispatchOnDemandTestEvent<
  TClientPayload extends {
    [k: string]: unknown
  }
> {
  action: "on-demand-test";
  branch: string;
  repository: Repository;
  sender: User;
  installation: InstallationLite;
  organization?: Organization;
  client_payload: TClientPayload
}

Missing 'converted_to_draft' and 'ready_for_review' actions on `pull_request` event

This is the reverse of the ready_for_review action that is already supported - triggered when a pull request is converted to a draft.

Github documentation has this as convert_to_draft, but the actual payload contains converted_to_draft:

Originally posted by @recurser in octokit/webhooks.js#399 (comment)

EDIT: It also seems the ready_for_review action is missing