octokit/webhooks octokit/webhooks

  • Stars
    star
    225
  • Rank 177,187 (Top 4 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created almost 6 years ago
  • Updated 29 days ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
octokit/webhooks
github

octokit

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

Octokit Webhooks

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

Update status

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

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.ts. 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

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:

LICENSE

MIT

More Repositories

1

octokit.js

The all-batteries-included GitHub SDK for Browsers, Node.js, and Deno.
TypeScript
6,955
star
2

octokit.rb

Ruby toolkit for the GitHub API
Ruby
3,848
star
3

octokit.net

A GitHub API client library for .NET
C#
2,679
star
4

octokit.objc

GitHub API client for Objective-C
Objective-C
1,838
star
5

core.js

Extendable client for GitHub's REST & GraphQL APIs
TypeScript
1,184
star
6

rest.js

GitHub REST API client for JavaScript
TypeScript
548
star
7

graphql.js

GitHub GraphQL API client for browsers and Node
TypeScript
465
star
8

request-action

A GitHub Action to send arbitrary requests to GitHub's REST API
JavaScript
369
star
9

authentication-strategies.js

GitHub API authentication strategies for Browsers, Node.js, and Deno
318
star
10

webhooks.js

GitHub webhook events toolset for Node.js
TypeScript
307
star
11

go-octokit

Simple Go wrapper for the GitHub API
Go
258
star
12

request.js

Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node
TypeScript
228
star
13

action.js

GitHub API client for GitHub Actions
TypeScript
185
star
14

graphql-schema

GitHub’s GraphQL Schema with validation. Automatically updated.
JavaScript
176
star
15

app.js

GitHub Apps toolset for Node.js
TypeScript
157
star
16

auth-app.js

GitHub App authentication for JavaScript
TypeScript
146
star
17

octokit.graphql.net

A GitHub GraphQL client library for .NET
C#
143
star
18

types.ts

Shared TypeScript definitions for Octokit projects
TypeScript
133
star
19

graphql-action

A GitHub Action to send queries to GitHub's GraphQL API
JavaScript
121
star
20

plugin-rest-endpoint-methods.js

Octokit plugin adding one method for all of api.github.com REST API endpoints
TypeScript
114
star
21

plugin-throttling.js

Octokit plugin for GitHub’s recommended request throttling
TypeScript
105
star
22

fixtures

Fixtures for all the octokittens
JavaScript
102
star
23

auth-token.js

GitHub API token authentication for browsers and Node.js
TypeScript
99
star
24

routes

machine-readable, always up-to-date GitHub REST API route specifications
JavaScript
84
star
25

oauth-app.js

GitHub OAuth toolset for Node.js
TypeScript
81
star
26

auth-oauth-app.js

GitHub OAuth App authentication for JavaScript
TypeScript
65
star
27

go-sdk

A generated Go SDK from GitHub's OpenAPI specification. Built on Kiota.
Go
64
star
28

endpoint.js

Turns REST API endpoints into generic request options
TypeScript
57
star
29

dotnet-sdk

C#
55
star
30

webhooks.net

GitHub webhook events toolset for .NET
C#
51
star
31

plugin-paginate-rest.js

Octokit plugin to paginate REST API endpoint responses
TypeScript
46
star
32

octopoller.rb

A micro gem for polling and retrying. Perfect for making repeating requests.
Ruby
45
star
33

auth-action.js

GitHub API token authentication for GitHub Actions
TypeScript
43
star
34

openapi

GitHub's official OpenAPI spec with Octokit extensions
JavaScript
43
star
35

plugin-paginate-graphql.js

Octokit plugin to paginate GraphQL Query responses
TypeScript
42
star
36

openapi-types.ts

Generated TypeScript definitions based on GitHub's OpenAPI spec
JavaScript
40
star
37

plugin-retry.js

Octokit plugin for GitHub’s recommended request retries
TypeScript
36
star
38

fixtures-server

Fixtures server for browser & language agnositic octokit testing
JavaScript
28
star
39

webhooks-methods.js

Methods to handle GitHub Webhook requests
TypeScript
23
star
40

octokit-next.js

JavaScript
21
star
41

plugin-enterprise-server.js

Octokit plugin for GitHub Enterprise REST APIs
TypeScript
19
star
42

auth-oauth-user-client.js

OAuth user authentication without exposing client secret
18
star
43

auth-oauth-user.js

Octokit authentication strategy for OAuth clients
TypeScript
17
star
44

create-octokit-project.js

"npm init" script to create a new Octokit JS module
JavaScript
16
star
45

oauth-authorization-url.js

Universal library to retrieve GitHub’s identity URL for the OAuth web flow
TypeScript
16
star
46

plugin-create-or-update-text-file.js

Convenience method to create/edit/delete a text file based on its current content
TypeScript
13
star
47

request-error.js

Error class for Octokit request errors
TypeScript
13
star
48

app-permissions

machine-readable, always up-to-date GitHub App permissions
JavaScript
12
star
49

auth-oauth-device.js

GitHub OAuth Device authentication strategy for JavaScript
TypeScript
10
star
50

handbook

Handbook for Octokit maintainers and GitHub integrators
9
star
51

auth-basic.js

GitHub API Basic authentication for browsers and Node.js
TypeScript
8
star
52

source-generator

Generates SDKs from GitHub's OpenAPI specification. Built on Kiota.
C#
8
star
53

discussions

discussions and planning for Octokit clients
7
star
54

plugin-request-log.js

Log all requests and request errors
TypeScript
7
star
55

plugin-enterprise-cloud.js

Octokit plugin for GitHub Enterprise Cloud REST APIs
TypeScript
7
star
56

.github

6
star
57

tsconfig

TypeScript configuration for Octokit packages
JavaScript
5
star
58

oauth-methods.js

Request methods to create and refresh user access tokens for OAuth and GitHub Apps
TypeScript
5
star
59

auth-callback.js

GitHub API authentication using a callback method
TypeScript
5
star
60

auth-unauthenticated.js

strategy for explicitly unauthenticated Octokit instances
TypeScript
5
star
61

tf-acc-test-empty-f89p1

Terraform acceptance test f89p1
2
star
62

plugin-enterprise-compatibility.js

Octokit plugin for improving GHE compatibility
TypeScript
2
star
63

openapi-webhooks

JavaScript
2
star
64

go-sdk-enterprise-server

A generated Go SDK from GitHub's OpenAPI specification, for the Enterprise Server product. Built on Kiota.
1
star
65

dotnet-sdk-enterprise-cloud

A generated .NET SDK from GitHub's OpenAPI specification, for the Enterprise Cloud product. Built on Kiota.
C#
1
star
66

go-sdk-enterprise-cloud

A generated Go SDK from GitHub's OpenAPI specification, for the Enterprise Cloud product. Built on Kiota.
Go
1
star
67

dotnet-sdk-enterprise-server

A generated .NET SDK from GitHub's OpenAPI specification, for the Enterprise Server product. Built on Kiota.
1
star