The GitHub Webhooks API lets you create and manage webhooks for repositories and organizations. Webhooks deliver HTTP POST payloads to a configured URL whenever specified events occur, such as pushes, pull requests, issues, and releases. The API supports creating, updating, deleting, and testing webhooks, as well as listing and redelivering webhook deliveries.
openapi: 3.1.0
info:
version: 1.1.4
title: github-repo-hooks-api
description: |-
Use the REST API to create, manage and control the workflow of public and
private GitHub repositories.
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
servers:
- url: '{protocol}://{hostname}'
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/
tags:
- name: Configuration
- name: Create
- name: Delete
- name: Deliveries
- name: Enforcement
- name: Get
- name: Hook
- name: Hooks
- name: Lists
- name: Ping
- name: Pre-Receive
- name: Push
- name: Re-Deliver
- name: Remove
- name: Repositories
description: Source control repositories.
- name: Tests
- name: Update
- name: Webhooks
paths:
/repos/{owner}/{repo}/hooks:
get:
summary: GitHub List Repository Webhooks
description: |-
Lists webhooks for a repository. `last response` may return null if there have not been any deliveries within 30 days.
tags:
- Lists
- Repositories
- Webhooks
operationId: listRepositoryWebhooks
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#list-repository-webhooks
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/hook'
examples:
default:
$ref: '#/components/examples/hook-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
x-api-evangelist-certified: '2025-07-16'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create Repository Webhook
description: |-
Repositories can have multiple webhooks installed. Each webhook should have a unique `config`. Multiple webhooks can
share the same `config` as long as those webhooks do not have any `events` that overlap.
tags:
- Create
- Repositories
- Webhooks
operationId: createRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#create-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: |-
Use `web` to create a webhook. Default: `web`. This parameter only accepts the value `web`.
config:
type: object
description: Key/value pairs to provide settings for this webhook.
properties:
url:
$ref: '#/components/schemas/webhook-config-url'
content_type:
$ref: '#/components/schemas/webhook-config-content-type'
secret:
$ref: '#/components/schemas/webhook-config-secret'
insecure_ssl:
$ref: '#/components/schemas/webhook-config-insecure-ssl'
events:
type: array
description: |-
Determines what [events](https://docs.github.com/[email protected]/webhooks/event-payloads) the hook is triggered for.
default:
- push
items:
type: string
active:
type: boolean
description: |-
Determines if notifications are sent when the webhook is triggered. Set to `true` to send notifications.
default: true
additionalProperties: false
examples:
default:
value:
name: web
active: true
events:
- push
- pull_request
config:
url: https://example.com/webhook
content_type: json
insecure_ssl: '0'
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/hook'
examples:
default:
$ref: '#/components/examples/hook'
headers:
Location:
example: https://api.github.com/repos/octocat/Hello-World/hooks/12345678
schema:
type: string
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}:
get:
summary: GitHub Get Repository Webhook
description: |-
Returns a webhook configured in a repository. To get only the webhook `config` properties, see "[Get webhook configuration for a repository](/rest/webhooks/repo-config#get-a-webhook-configuration-for-a-repository)."
tags:
- Get
- Repositories
- Webhooks
operationId: getRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#get-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/hook'
examples:
default:
$ref: '#/components/examples/hook'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Repository Webhook
description: |-
Updates a webhook configured in a repository. If you previously had a `secret` set, you must provide the same `secret` or set a new `secret` or the secret will be removed. If you are only updating individual webhook `config` properties, use "[Update a webhook configuration for a repository](/rest/webhooks/repo-config#update-a-webhook-configuration-for-a-repository)."
tags:
- Repositories
- Update
- Webhooks
operationId: updateRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#update-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/webhook-config'
events:
type: array
description: |-
Determines what [events](https://docs.github.com/[email protected]/webhooks/event-payloads) the hook is triggered for. This replaces the entire array of events.
default:
- push
items:
type: string
add_events:
type: array
description: |-
Determines a list of events to be added to the list of events that the Hook triggers for.
items:
type: string
remove_events:
type: array
description: |-
Determines a list of events to be removed from the list of events that the Hook triggers for.
items:
type: string
active:
type: boolean
description: |-
Determines if notifications are sent when the webhook is triggered. Set to `true` to send notifications.
default: true
examples:
default:
value:
active: true
add_events:
- pull_request
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/hook'
examples:
default:
$ref: '#/components/examples/hook'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Repository Webhook
description: |-
This API operation deletes a specific webhook from a GitHub repository by sending a DELETE request to the endpoint /repos/{owner}/{repo}/hooks/{hook_id}. The operation requires three path parameters: the repository owner's username, the repository name, and the unique identifier of the webhook to be removed. Upon successful execution, the webhook is permanently deleted from the repository, meaning it will no longer receive or trigger events for that repository. This operation typically requires appropriate authentication and repository admin permissions to execute, and it returns a 204 No Content status code when the deletion is successful.
tags:
- Delete
- Repositories
- Webhooks
operationId: deleteRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#delete-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/config:
get:
summary: GitHub Get Webhook Configuration for Repository
description: |-
Returns the webhook configuration for a repository. To get more information about the webhook, including the `active` state and `events`, use "[Get repository webhook](/rest/webhooks/repos#get-a-repository-webhook)."
OAuth app tokens and personal access tokens (classic) need the `read:repo_hook` or `repo` scope to use this endpoint.
tags:
- Configuration
- Get
- Repositories
- Webhooks
operationId: getWebhookConfigurationForRepository
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#get-a-webhook-configuration-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-config'
examples:
default:
$ref: '#/components/examples/webhook-config'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Webhook Configuration for Repository
description: |-
Updates the webhook configuration for a repository. To update more information about the webhook, including the `active` state and `events`, use "[Update a repository webhook](/rest/webhooks/repos#update-a-repository-webhook)."
OAuth app tokens and personal access tokens (classic) need the `write:repo_hook` or `repo` scope to use this endpoint.
tags:
- Configuration
- Repositories
- Update
- Webhooks
operationId: updateWebhookConfigurationForRepository
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#update-a-webhook-configuration-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
url:
$ref: '#/components/schemas/webhook-config-url'
content_type:
$ref: '#/components/schemas/webhook-config-content-type'
secret:
$ref: '#/components/schemas/webhook-config-secret'
insecure_ssl:
$ref: '#/components/schemas/webhook-config-insecure-ssl'
examples:
default:
summary: Example of updating content type and URL
value:
content_type: json
url: https://example.com/webhook
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-config'
examples:
default:
$ref: '#/components/examples/webhook-config'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/deliveries:
get:
summary: GitHub List Deliveries for Repository Webhook
description: |-
Returns a list of webhook deliveries for a webhook configured in a repository.
tags:
- Deliveries
- Lists
- Repositories
- Webhooks
operationId: listDeliveriesForRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#list-deliveries-for-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/cursor'
- name: redelivery
in: query
required: false
schema:
type: boolean
example: true
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/hook-delivery-item'
examples:
default:
$ref: '#/components/examples/hook-delivery-items'
'400':
$ref: '#/components/responses/bad_request'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}:
get:
summary: GitHub Get Delivery for Repository Webhook
description: Returns a delivery for a webhook configured in a repository.
tags:
- Deliveries
- Get
- Repositories
- Webhooks
operationId: getDeliveryForRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#get-a-delivery-for-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- $ref: '#/components/parameters/delivery-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/hook-delivery'
examples:
default:
$ref: '#/components/examples/hook-delivery'
'400':
$ref: '#/components/responses/bad_request'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts:
post:
summary: GitHub Redeliver Delivery for Repository Webhook
description: Redeliver a webhook delivery for a webhook configured in a repository.
tags:
- Deliveries
- Re-Deliver
- Repositories
- Webhooks
operationId: redeliverDeliveryForRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#redeliver-a-delivery-for-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- $ref: '#/components/parameters/delivery-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'202':
$ref: '#/components/responses/accepted'
'400':
$ref: '#/components/responses/bad_request'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/pings:
post:
summary: GitHub Ping Repository Webhook
description: |-
This will trigger a [ping event](https://docs.github.com/[email protected]/webhooks/#ping-event) to be sent to the hook.
tags:
- Ping
- Repositories
- Webhooks
operationId: pingRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#ping-a-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/hooks/{hook_id}/tests:
post:
summary: GitHub Test the Push Repository Webhook
description: |-
This will trigger the hook with the latest push to the current repository if the hook is subscribed to `push` events. If the hook is not subscribed to `push` events, the server will respond with 204 but no test POST will be generated.
**Note**: Previously `/repos/:owner/:repo/hooks/:hook_id/test`
tags:
- Push
- Repositories
- Tests
- Webhooks
operationId: testThePushRepositoryWebhook
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/repos/webhooks#test-the-push-repository-webhook
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pre-receive-hooks:
get:
summary: GitHub List Pre-receive Hooks for Repository
description: |-
List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.
operationId: listPrereceiveHooksForRepository
tags:
- Hooks
- Lists
- Pre-Receive
- Repositories
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/enterprise-admin/repo-pre-receive-hooks#list-pre-receive-hooks-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/direction'
- name: sort
in: query
required: false
schema:
type: string
enum:
- created
- updated
- name
default: created
example: created
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/repository-pre-receive-hook'
examples:
default:
$ref: '#/components/examples/repository-pre-receive-hook-items'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: enterprise-admin
subcategory: repo-pre-receive-hooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}:
get:
summary: GitHub Get Pre-receive Hook for Repository
description: |-
This API endpoint retrieves detailed information about a specific pre-receive hook configured for a GitHub repository. Pre-receive hooks are scripts that run on the GitHub server before code is accepted into a repository, allowing administrators to enforce quality standards or policies. By providing the repository owner, repository name, and the pre-receive hook ID in the URL path, this GET operation returns comprehensive details about that particular hook, including its configuration, enforcement level, and current status within the specified repository.
operationId: getPrereceiveHookForRepository
tags:
- Get
- Hook
- Pre-Receive
- Repositories
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/enterprise-admin/repo-pre-receive-hooks#get-a-pre-receive-hook-for-a-repository
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/pre-receive-hook-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/repository-pre-receive-hook'
examples:
default:
$ref: '#/components/examples/repository-pre-receive-hook'
x-gi
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-repo-hooks-api-openapi.yml