GitHub Events API
The GitHub Events API provides a read-only feed of recent activity on GitHub, exposing structured event objects you can poll to see what happened across the platform or within a specific repository, organization, or user account. It covers many event typessuch as pushes, pull requests, issues, comments, releases, stars, forks, and membership changeseach with consistent metadata (actor, repo, type, payload, timestamps, IDs).
Documentation
Specifications
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Events API
description: Use the REST API to interact with GitHub events.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Authenticated
- name: Events
- name: Get
- name: Issues
- name: Lists
- name: Organizations
- name: Public
- name: Users
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/repos/{owner}/{repo}/issues/events/{event_id}:
get:
summary: GitHub Get an Issue Event
description: >-
The Get An Issue Event operation retrieves detailed information about a
specific event that occurred on an issue within a GitHub repository. By
providing the repository owner, repository name, and a unique event ID
through the endpoint path parameters, this API returns comprehensive
data about that particular issue event, such as when it was created, the
type of event (like labeled, assigned, closed, etc.), the actor who
triggered the event, and any associated metadata. This is useful for
tracking the complete history and timeline of changes made to issues,
enabling developers and project managers to audit issue activity,
understand workflow patterns, and maintain detailed records of how
issues evolved over time within their projects.
tags:
- Events
- Get
- Issues
operationId: getAnIssueEvent
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/issues/events#get-an-issue-event
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: event_id
in: path
required: true
schema:
type: integer
example: 42
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/issue-event'
examples:
default:
$ref: '#/components/examples/issue-event'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'410':
$ref: '#/components/responses/gone'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: events
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{username}/events/orgs/{org}:
get:
summary: GitHub List Organization Events for the Authenticated User
description: >-
The GitHub Events API endpoint `/users/{username}/events/orgs/{org}`
using the GET method retrieves a list of events for the authenticated
user within a specific organization. This endpoint allows developers to
access activity data related to a particular organization that the
authenticated user is associated with, providing visibility into
organization-level events and actions. The API returns event data in a
paginated format, showing activities such as repository changes, issue
updates, pull requests, and other collaborative actions performed within
the specified organization context. Authentication is required to access
this endpoint, and the results are filtered to show only events relevant
to both the specified username and organization that the authenticated
user has permission to view.
tags:
- Authenticated
- Events
- Lists
- Organizations
- Users
operationId: listOrganizationEventsForTheAuthenticatedUser
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/activity/events#list-organization-events-for-the-authenticated-user
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event'
examples:
default:
$ref: '#/components/examples/user-org-events-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: activity
subcategory: events
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{username}/events/public:
get:
summary: GitHub List Public Events for User
description: >-
The List Public Events For A User operation retrieves a paginated list
of public events performed by a specified GitHub user. This GET endpoint
accepts a username as a path parameter and returns events such as
repository pushes, issue comments, pull requests, and other public
activities associated with that user's account. The response includes
event metadata like timestamps, event types, and related repository
information, making it useful for tracking user contributions and
activity across GitHub's public repositories. This endpoint supports
pagination parameters and requires no authentication for accessing
public event data, though authenticated requests have higher rate
limits.
tags:
- Events
- Lists
- Public
- Users
operationId: listPublicEventsForUser
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/activity/events#list-public-events-for-a-user
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/event'
examples:
default:
$ref: '#/components/examples/user-public-events-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: activity
subcategory: events
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
x-webhooks:
branch-protection-rule-created:
post:
summary: >-
This event occurs when there is activity relating to branch protection
rules. For more information, see "[About protected
branches](https://docs.github.com/[email protected]/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)."
For information about the APIs to manage branch protection rules, see
[the GraphQL
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#branchprotectionrule)
or "[Branch
protection](https://docs.github.com/[email protected]/rest/branches/branch-protection)"
in the REST API documentation.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Administration" repository permission.
description: A branch protection rule was created.
operationId: branch-protection-rule/created
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#branch_protection_rule
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-branch-protection-rule-created'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
category: webhooks
subcategory: branch_protection_rule
supported-webhook-types:
- repository
- organization
- app
branch-protection-rule-deleted:
post:
summary: >-
This event occurs when there is activity relating to branch protection
rules. For more information, see "[About protected
branches](https://docs.github.com/[email protected]/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)."
For information about the APIs to manage branch protection rules, see
[the GraphQL
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#branchprotectionrule)
or "[Branch
protection](https://docs.github.com/[email protected]/rest/branches/branch-protection)"
in the REST API documentation.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Administration" repository permission.
description: A branch protection rule was deleted.
operationId: branch-protection-rule/deleted
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#branch_protection_rule
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-branch-protection-rule-deleted'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
category: webhooks
subcategory: branch_protection_rule
supported-webhook-types:
- repository
- organization
- app
branch-protection-rule-edited:
post:
summary: >-
This event occurs when there is activity relating to branch protection
rules. For more information, see "[About protected
branches](https://docs.github.com/[email protected]/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)."
For information about the APIs to manage branch protection rules, see
[the GraphQL
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#branchprotectionrule)
or "[Branch
protection](https://docs.github.com/[email protected]/rest/branches/branch-protection)"
in the REST API documentation.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Administration" repository permission.
description: A branch protection rule was edited.
operationId: branch-protection-rule/edited
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#branch_protection_rule
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-branch-protection-rule-edited'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
category: webhooks
subcategory: branch_protection_rule
supported-webhook-types:
- repository
- organization
- app
cache-sync:
post:
summary: >-
This event occurs when a Git ref has been successfully synced to a cache
replica. For more information, see "[About repository
caching](https://docs.github.com/[email protected]/admin/enterprise-management/caching-repositories/about-repository-caching)."
operationId: cache-sync
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#cache_sync
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-cache-sync'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
category: webhooks
subcategory: cache_sync
supported-webhook-types:
- repository
- organization
- app
check-run-completed:
post:
summary: >-
This event occurs when there is activity relating to a check run. For
information about check runs, see "[Getting started with the Checks
API](https://docs.github.com/[email protected]/rest/guides/getting-started-with-the-checks-api)."
For information about the APIs to manage check runs, see [the GraphQL
API
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#checkrun)
or "[Check
Runs](https://docs.github.com/[email protected]/rest/checks/runs)"
in the REST API documentation.
For activity relating to check suites, use the `check-suite` event.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Checks" repository permission. To receive the
`rerequested` and `requested_action` event types, the app must have at
least write-level access for the "Checks" permission. GitHub Apps with
write-level access for the "Checks" permission are automatically
subscribed to this webhook event.
Repository and organization webhooks only receive payloads for the
`created` and `completed` event types in repositories.
**Note**: The API only looks for pushes in the repository where the
check run was created. Pushes to a branch in a forked repository are not
detected and return an empty `pull_requests` array and a `null` value
for `head_branch`.
description: A check run was completed, and a conclusion is available.
operationId: check-run/completed
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#check_run
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-check-run-completed'
examples:
default:
$ref: '#/components/examples/check-run-completed'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/webhook-check-run-completed-form-encoded'
examples:
default:
$ref: '#/components/examples/check-run-completed-form-encoded'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: webhooks
subcategory: check_run
supported-webhook-types:
- repository
- organization
- app
check-run-created:
post:
summary: >-
This event occurs when there is activity relating to a check run. For
information about check runs, see "[Getting started with the Checks
API](https://docs.github.com/[email protected]/rest/guides/getting-started-with-the-checks-api)."
For information about the APIs to manage check runs, see [the GraphQL
API
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#checkrun)
or "[Check
Runs](https://docs.github.com/[email protected]/rest/checks/runs)"
in the REST API documentation.
For activity relating to check suites, use the `check-suite` event.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Checks" repository permission. To receive the
`rerequested` and `requested_action` event types, the app must have at
least write-level access for the "Checks" permission. GitHub Apps with
write-level access for the "Checks" permission are automatically
subscribed to this webhook event.
Repository and organization webhooks only receive payloads for the
`created` and `completed` event types in repositories.
**Note**: The API only looks for pushes in the repository where the
check run was created. Pushes to a branch in a forked repository are not
detected and return an empty `pull_requests` array and a `null` value
for `head_branch`.
description: A new check run was created.
operationId: check-run/created
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#check_run
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-check-run-created'
examples:
default:
$ref: '#/components/examples/check-run-created'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/webhook-check-run-created-form-encoded'
examples:
default:
$ref: '#/components/examples/check-run-created-form-encoded'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: webhooks
subcategory: check_run
supported-webhook-types:
- repository
- organization
- app
check-run-requested-action:
post:
summary: >-
This event occurs when there is activity relating to a check run. For
information about check runs, see "[Getting started with the Checks
API](https://docs.github.com/[email protected]/rest/guides/getting-started-with-the-checks-api)."
For information about the APIs to manage check runs, see [the GraphQL
API
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#checkrun)
or "[Check
Runs](https://docs.github.com/[email protected]/rest/checks/runs)"
in the REST API documentation.
For activity relating to check suites, use the `check-suite` event.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Checks" repository permission. To receive the
`rerequested` and `requested_action` event types, the app must have at
least write-level access for the "Checks" permission. GitHub Apps with
write-level access for the "Checks" permission are automatically
subscribed to this webhook event.
Repository and organization webhooks only receive payloads for the
`created` and `completed` event types in repositories.
**Note**: The API only looks for pushes in the repository where the
check run was created. Pushes to a branch in a forked repository are not
detected and return an empty `pull_requests` array and a `null` value
for `head_branch`.
description: >-
A check run completed, and someone requested a followup action that your
app provides. Only the GitHub App someone requests to perform an action
will receive the `requested_action` payload. For more information, see
"[Creating CI tests with the Checks
API](https://docs.github.com/[email protected]/developers/apps/guides/creating-ci-tests-with-the-checks-api)."
operationId: check-run/requested-action
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#check_run
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Event
in: header
example: issues
schema:
type: string
- name: X-Github-Hook-Installation-Target-Id
in: header
example: 123123
schema:
type: string
- name: X-Github-Hook-Installation-Target-Type
in: header
example: repository
schema:
type: string
- name: X-GitHub-Delivery
in: header
example: 0b989ba4-242f-11e5-81e1-c7b6966d2516
schema:
type: string
- name: X-Hub-Signature-256
in: header
example: sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e
schema:
type: string
- name: X-GitHub-Enterprise-Version
in: header
example: 3.1.9
schema:
type: string
- name: X-GitHub-Enterprise-Host
in: header
example: ghes.github.com
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-check-run-requested-action'
examples:
default:
$ref: '#/components/examples/check-run-requested-action'
application/x-www-form-urlencoded:
schema:
$ref: >-
#/components/schemas/webhook-check-run-requested-action-form-encoded
examples:
default:
$ref: '#/components/examples/check-run-requested-action-form-encoded'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: webhooks
subcategory: check_run
supported-webhook-types:
- repository
- organization
- app
check-run-rerequested:
post:
summary: >-
This event occurs when there is activity relating to a check run. For
information about check runs, see "[Getting started with the Checks
API](https://docs.github.com/[email protected]/rest/guides/getting-started-with-the-checks-api)."
For information about the APIs to manage check runs, see [the GraphQL
API
documentation](https://docs.github.com/[email protected]/graphql/reference/objects#checkrun)
or "[Check
Runs](https://docs.github.com/[email protected]/rest/checks/runs)"
in the REST API documentation.
For activity relating to check suites, use the `check-suite` event.
To subscribe to this event, a GitHub App must have at least read-level
access for the "Checks" repository permission. To receive the
`rerequested` and `requested_action` event types, the app must have at
least write-level access for the "Checks" permission. GitHub Apps with
write-level access for the "Checks" permission are automatically
subscribed to this webhook event.
Repository and organization webhooks only receive payloads for the
`created` and `completed` event types in repositories.
**Note**: The API only looks for pushes in the repository where the
check run was created. Pushes to a branch in a forked repository are not
detected and return an empty `pull_requests` array and a `null` value
for `head_branch`.
description: >-
Someone requested to re-run a check run. Only the GitHub App that
someone requests to re-run the check will receive the `rerequested`
payload.
operationId: check-run/rerequested
externalDocs:
url: >-
https://docs.github.com/[email protected]/webhooks/webhook-events-and-payloads#check_run
parameters:
- name: User-Agent
in: header
example: GitHub-Hookshot/123abc
schema:
type: string
- name: X-Github-Hook-Id
in: header
example: 12312312
schema:
type: string
- name: X-Github-Eve
# --- truncated at 32 KB (6511 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-events-api-openapi.yml