openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Webhooks API
description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App
installations.'
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
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
tags:
- name: Webhooks
paths:
/app/hook/config:
get:
summary: GitHub Getwebhook Configuration for an App
description: 'Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "[Creating a GitHub App](/developers/apps/creating-a-github-app)."
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Webhooks
operationId: getwebhookConfigurationForAnApp
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/webhooks#get-a-webhook-configuration-for-an-app
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: false
category: apps
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Updatewebhook Configuration for an App
description: 'Updates the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "[Creating a GitHub App](/developers/apps/creating-a-github-app)."
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Webhooks
operationId: updatewebhookConfigurationForAnApp
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/webhooks#update-a-webhook-configuration-for-an-app
requestBody:
required: true
content:
application/json:
schema:
type: object
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:
value:
content_type: json
insecure_ssl: '0'
secret: '********'
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: false
category: apps
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/app/hook/deliveries:
get:
summary: GitHub List Deliveries for an App Webhook
description: 'Returns a list of webhook deliveries for the webhook configured for a GitHub App.
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Webhooks
operationId: listDeliveriesForAnAppWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/webhooks#list-deliveries-for-an-app-webhook
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/cursor'
- name: redelivery
in: query
required: false
schema:
type: boolean
example: true
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: false
category: apps
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/app/hook/deliveries/{delivery_id}:
get:
summary: GitHub Getdelivery for an App Webhook
description: 'Returns a delivery for the webhook configured for a GitHub App.
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Webhooks
operationId: getdeliveryForAnAppWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/webhooks#get-a-delivery-for-an-app-webhook
parameters:
- $ref: '#/components/parameters/delivery-id'
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: false
category: apps
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/app/hook/deliveries/{delivery_id}/attempts:
post:
summary: GitHub Redeliverdelivery for an App Webhook
description: 'Redeliver a delivery for the webhook configured for a GitHub App.
You must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.'
tags:
- Webhooks
operationId: redeliverdeliveryForAnAppWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/webhooks#redeliver-a-delivery-for-an-app-webhook
parameters:
- $ref: '#/components/parameters/delivery-id'
responses:
'202':
$ref: '#/components/responses/accepted'
'400':
$ref: '#/components/responses/bad_request'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: apps
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks:
get:
summary: GitHub List Organization Webhooks
description: This API endpoint retrieves a list of all webhooks configured for a specified GitHub organization. By making a GET request to /orgs/{org}/hooks with the organization name as a path parameter, authenticated users with appropriate permissions can view all active webhooks including their configurations, events they're subscribed to, delivery URLs, and other metadata. This operation requires the user to have admin access to the organization and is commonly used for auditing webhook configurations, managing integrations, or programmatically discovering what external services are receiving notifications from the organization's activities.
tags:
- Webhooks
operationId: listOrganizationWebhooks
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#list-organization-webhooks
parameters:
- $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/org-hook'
examples:
default:
$ref: '#/components/examples/org-hook-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Create an Organization Webhook
description: This API operation allows you to create a new webhook for a specified GitHub organization by sending a POST request to the /orgs/{org}/hooks endpoint, where {org} is replaced with the organization name. Webhooks enable real-time notifications when specific events occur within the organization, such as repository creation, team modifications, or membership changes. When creating the webhook, you must provide configuration details including the payload URL where GitHub will send HTTP POST payloads, the content type, optional secret for securing payloads, and specify which events should trigger the webhook. The operation requires admin privileges for the organization and returns the newly created webhook object containing its unique identifier, configuration settings, and metadata. This functionality is essential for integrating GitHub organizations with external services, CI/CD pipelines, monitoring systems, or custom automation workflows that need to respond to organizational events.
tags:
- Webhooks
operationId: createAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#create-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Must be passed as "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'
username:
type: string
example: '"kdaigle"'
password:
type: string
example: '"password"'
required:
- url
events:
type: array
description: Determines what [events](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads) the hook is triggered for. Set to `["*"]` to receive all possible events.
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
required:
- name
- config
examples:
default:
value:
name: web
active: true
events:
- push
- pull_request
config:
url: http://example.com/webhook
content_type: json
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/org-hook'
examples:
default:
$ref: '#/components/examples/org-hook'
headers:
Location:
example: https://api.github.com/orgs/octocat/hooks/1
schema:
type: string
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}:
get:
summary: GitHub Get an Organization Webhook
description: Returns a webhook configured in an organization. To get only the webhook `config` properties, see "[Get a webhook configuration for an organization](/rest/orgs/webhooks#get-a-webhook-configuration-for-an-organization)."
tags:
- Webhooks
operationId: getAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#get-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/org-hook'
examples:
default:
$ref: '#/components/examples/org-hook'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Organization Webhook
description: Updates a webhook configured in an organization. When you update a webhook, the `secret` will be overwritten. 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 an organization](/rest/orgs/webhooks#update-a-webhook-configuration-for-an-organization)."
tags:
- Webhooks
operationId: updateAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#update-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
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'
required:
- url
events:
type: array
description: Determines what [events](https://docs.github.com/enterprise-server@3.9/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
name:
type: string
example: '"web"'
examples:
default:
value:
active: true
events:
- pull_request
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/org-hook'
examples:
default:
$ref: '#/components/examples/org-hook-2'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete an Organization Webhook
description: This API operation removes a webhook from a specified GitHub organization by making a DELETE request to the endpoint with the organization name and webhook ID as path parameters. When executed, it permanently deletes the specified webhook configuration, including its delivery URL, events it was subscribed to, and any associated settings. This operation requires appropriate administrative permissions for the organization and returns a 204 No Content status code upon successful deletion, with no response body returned.
tags:
- Webhooks
operationId: deleteAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#delete-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}/config:
get:
summary: GitHub Get Webhook Configuration for an Organization
description: 'Returns the webhook configuration for an organization. To get more information about the webhook, including the `active` state and `events`, use "[Get an organization webhook ](/rest/orgs/webhooks#get-an-organization-webhook)."
OAuth app tokens and personal access tokens (classic) need the `admin:org_hook` scope to use this endpoint.'
tags:
- Webhooks
operationId: getWebhookConfigurationForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#get-a-webhook-configuration-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
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: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Webhook Configuration for an Organization
description: 'Updates the webhook configuration for an organization. To update more information about the webhook, including the `active` state and `events`, use "[Update an organization webhook ](/rest/orgs/webhooks#update-an-organization-webhook)."
OAuth app tokens and personal access tokens (classic) need the `admin:org_hook` scope to use this endpoint.'
tags:
- Webhooks
operationId: updateWebhookConfigurationForAnOrganization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#update-a-webhook-configuration-for-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
requestBody:
required: false
content:
application/json:
schema:
type: object
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: Update an existing webhook
value:
url: http://example.com/webhook
content_type: json
insecure_ssl: '0'
secret: '********'
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: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}/deliveries:
get:
summary: GitHub List Deliveries for an Organization Webhook
description: Returns a list of webhook deliveries for a webhook configured in an organization. This endpoint allows you to retrieve the delivery history for a specific organization webhook, showing details about each time the webhook was triggered and the HTTP request was sent to the configured URL. Each delivery record includes information such as the delivery ID, status, timestamp, and other metadata about the webhook event that was fired. This is useful for debugging webhook integrations, monitoring webhook reliability, and tracking which events have been sent to your webhook endpoint.
tags:
- Webhooks
operationId: listDeliveriesForAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#list-deliveries-for-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $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
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: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}:
get:
summary: GitHub Get Webhook Delivery for an Organization Webhook
description: This API operation retrieves detailed information about a specific webhook delivery attempt for an organization-level webhook in GitHub. By providing the organization name, webhook ID, and delivery ID as path parameters, you can access comprehensive data about a particular delivery event, including the request and response details, headers, payload, status code, and timestamp. This is useful for debugging webhook issues, monitoring delivery success rates, and understanding how your webhooks are performing when triggered by organization events. The endpoint requires appropriate authentication and permissions to access the organization's webhook configuration and delivery history.
tags:
- Webhooks
operationId: getWebhookDeliveryForAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#get-a-webhook-delivery-for-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
- $ref: '#/components/parameters/delivery-id'
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: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts:
post:
summary: GitHub Redeliver Delivery for an Organization Webhook
description: Redeliver a delivery for a webhook configured in an organization.
tags:
- Webhooks
operationId: redeliverDeliveryForAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#redeliver-a-delivery-for-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
- $ref: '#/components/parameters/delivery-id'
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: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/hooks/{hook_id}/pings:
post:
summary: GitHub Ping an Organization Webhook
description: This will trigger a [ping event](https://docs.github.com/enterprise-server@3.9/webhooks/#ping-event) to be sent to the hook.
tags:
- Webhooks
operationId: pingAnOrganizationWebhook
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/orgs/webhooks#ping-an-organization-webhook
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/hook-id'
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: orgs
subcategory: webhooks
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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:
- Webhooks
operationId: listRepositoryWebhooks
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/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:
# --- truncated at 32 KB (685 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-webhooks-api-openapi.yml