Skip to main content
Free, Pro, & Team
English
Sign up
 
REST API
Free, Pro, & Team
English
Sign up

 

We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.

Webhooks

In this article

The webhooks API allows you to create and manage webhooks for your repositories.

Repository webhooks allow you to receive HTTP POST payloads whenever certain events happen in a repository. The webhook REST APIs enable you to manage repository, organization, and app webhooks. You can use this API to list webhook deliveries for a webhook, or get and redeliver an individual delivery for a webhook, which can be integrated into an external app or service. You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:

If you would like to set up a single webhook to receive events from all of your organization's repositories, see our API documentation for Organization Webhooks.

In addition to the REST API, GitHub can also serve as a PubSubHubbub hub for repositories.

Receiving Webhooks

In order for GitHub to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.

Webhook headers

GitHub will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.

PubSubHubbub

GitHub can also serve as a PubSubHubbub hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL. Topic URLs for a GitHub repository's pushes are in this format:

https://github.com/{owner}/{repo}/events/{event}

The event can be any available webhook event. For more information, see "Webhook events and payloads."

Response format

The default format is what existing post-receive hooks should expect: A JSON body sent as the payload parameter in a POST. You can also specify to receive the raw JSON body with either an Accept header, or a .json extension.

Accept: application/json
https://github.com/{owner}/{repo}/events/push.json

Callback URLs

Callback URLs can use the http:// protocol.

# Send updates to postbin.org
http://postbin.org/123

Subscribing

The GitHub PubSubHubbub endpoint is: https://api.github.com/hub. A successful request with curl looks like:

curl -u "user" -i \
  https://api.github.com/hub \
  -F "hub.mode=subscribe" \
  -F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
  -F "hub.callback=http://postbin.org/123"

PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.

Parameters

NameTypeDescription
hub.modestringRequired. Either subscribe or unsubscribe.
hub.topicstringRequired. The URI of the GitHub repository to subscribe to. The path must be in the format of /{owner}/{repo}/events/{event}.
hub.callbackstringThe URI to receive the updates to the topic.
hub.secretstringA shared secret key that generates a hash signature of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the X-Hub-Signature or X-Hub-Signature-256 headers. You can see the PubSubHubbub documentation for more details.

Repository webhook configuration

Get a webhook configuration for a repository

Returns the webhook configuration for a repository. To get more information about the webhook, including the active state and events, use "Get a repository webhook."

Access tokens must have the read:repo_hook or repo scope, and GitHub Apps must have the repository_hooks:read permission.

get /repos/{owner}/{repo}/hooks/{hook_id}/config

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/config
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}/config', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 200 OK
 {
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

Notes

Update a webhook configuration for a repository

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

Access tokens must have the write:repo_hook or repo scope, and GitHub Apps must have the repository_hooks:write permission.

patch /repos/{owner}/{repo}/hooks/{hook_id}/config

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath
urlstringbody

The URL to which the payloads will be delivered.

content_typestringbody

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstringbody

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring or number or body

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Code samples

Shell
 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/config \
  -d '{"url":"url"}'
JavaScript (@octokit/core.js)
 await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}/config', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42,
  url: 'url'
})

Response

 Status: 200 OK
 {
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

Notes

Repository webhook deliveries

List deliveries for a repository webhook

Returns a list of webhook deliveries for a webhook configured in a repository.

get /repos/{owner}/{repo}/hooks/{hook_id}/deliveries

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath
per_pageintegerquery

Results per page (max 100)

Default: 30

cursorstringquery

Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the link header for the next and previous page cursors.

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/deliveries
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveries', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 200 OK
 [
  {
    "id": 12345678,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-03T00:57:16Z",
    "redelivery": false,
    "duration": 0.27,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  },
  {
    "id": 123456789,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-04T00:57:16Z",
    "redelivery": true,
    "duration": 0.28,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  }
]

Bad Request

 Status: 400 Bad Request

Validation failed

 Status: 422 Unprocessable Entity

Notes

Get a delivery for a repository webhook

Returns a delivery for a webhook configured in a repository.

get /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath
delivery_idintegerpath

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/deliveries/42
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42,
  delivery_id: 42
})

Response

 Status: 200 OK
 {
  "id": 12345678,
  "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
  "delivered_at": "2019-06-03T00:57:16Z",
  "redelivery": false,
  "duration": 0.27,
  "status": "OK",
  "status_code": 200,
  "event": "issues",
  "action": "opened",
  "installation_id": 123,
  "repository_id": 456,
  "url": "https://www.example.com",
  "request": {
    "headers": {
      "X-GitHub-Delivery": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
      "X-Hub-Signature-256": "sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "Accept": "*/*",
      "X-GitHub-Hook-ID": "42",
      "User-Agent": "GitHub-Hookshot/b8c71d8",
      "X-GitHub-Event": "issues",
      "X-GitHub-Hook-Installation-Target-ID": "123",
      "X-GitHub-Hook-Installation-Target-Type": "repository",
      "content-type": "application/json",
      "X-Hub-Signature": "sha1=a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d"
    },
    "payload": {
      "action": "opened",
      "issue": {
        "body": "foo"
      },
      "repository": {
        "id": 123
      }
    }
  },
  "response": {
    "headers": {
      "Content-Type": "text/html;charset=utf-8"
    },
    "payload": "ok"
  }
}

Bad Request

 Status: 400 Bad Request

Validation failed

 Status: 422 Unprocessable Entity

Notes

Redeliver a delivery for a repository webhook

Redeliver a webhook delivery for a webhook configured in a repository.

post /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath
delivery_idintegerpath

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/deliveries/42/attempts
JavaScript (@octokit/core.js)
 await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42,
  delivery_id: 42
})

Accepted

 Status: 202 Accepted

Bad Request

 Status: 400 Bad Request

Validation failed

 Status: 422 Unprocessable Entity

Notes

Repository webhooks

List repository webhooks

get /repos/{owner}/{repo}/hooks

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
per_pageintegerquery

Results per page (max 100)

Default: 30

pageintegerquery

Page number of the results to fetch.

Default: 1

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/hooks', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

 Status: 200 OK
 [
  {
    "type": "Repository",
    "id": 12345678,
    "name": "web",
    "active": true,
    "events": [
      "push",
      "pull_request"
    ],
    "config": {
      "content_type": "json",
      "insecure_ssl": "0",
      "url": "https://example.com/webhook"
    },
    "updated_at": "2019-06-03T00:57:16Z",
    "created_at": "2019-06-03T00:57:16Z",
    "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
    "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
    "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
    "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
    "last_response": {
      "code": null,
      "status": "unused",
      "message": null
    }
  }
]

Resource not found

 Status: 404 Not Found

Notes

Create a repository webhook

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.

post /repos/{owner}/{repo}/hooks

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
namestringbody

Use web to create a webhook. Default: web. This parameter only accepts the value web.

configobjectbody

Key/value pairs to provide settings for this webhook. These are defined below.

Name (Type)Description
url (string)

The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_ssl (string or number or )

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

token (string)
digest (string)
eventsarray of stringsbody

Determines what events the hook is triggered for.

Default: push

activebooleanbody

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default:

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
 await octokit.request('POST /repos/{owner}/{repo}/hooks', {
  owner: 'octocat',
  repo: 'hello-world',
  name: 'name'
})

Response

 Status: 201 Created
 {
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

Forbidden

 Status: 403 Forbidden

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Get a repository webhook

Returns a webhook configured in a repository. To get only the webhook config properties, see "Get a webhook configuration for a repository."

get /repos/{owner}/{repo}/hooks/{hook_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath

Code samples

Shell
 curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
 await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 200 OK
 {
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

Resource not found

 Status: 404 Not Found

Notes

Update a repository webhook

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

patch /repos/{owner}/{repo}/hooks/{hook_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath
configobjectbody

Key/value pairs to provide settings for this webhook. These are defined below.

Name (Type)Description
url (string)

Required. The URL to which the payloads will be delivered.

content_type (string)

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secret (string)

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_ssl (string or number or )

Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

address (string)
room (string)
eventsarray of stringsbody

Determines what events the hook is triggered for. This replaces the entire array of events.

Default: push

add_eventsarray of stringsbody

Determines a list of events to be added to the list of events that the Hook triggers for.

remove_eventsarray of stringsbody

Determines a list of events to be removed from the list of events that the Hook triggers for.

activebooleanbody

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default:

Code samples

Shell
 curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42 \
  -d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl","address":"address","room":"room"}}'
JavaScript (@octokit/core.js)
 await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42,
  config: {
    url: 'url',
    content_type: 'content_type',
    secret: 'secret',
    insecure_ssl: 'insecure_ssl',
    address: 'address',
    room: 'room'
  }
})

Response

 Status: 200 OK
 {
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

Resource not found

 Status: 404 Not Found

Validation failed

 Status: 422 Unprocessable Entity

Notes

Delete a repository webhook

delete /repos/{owner}/{repo}/hooks/{hook_id}

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath

Code samples

Shell
 curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
 await octokit.request('DELETE /repos/{owner}/{repo}/hooks/{hook_id}', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 204 No Content

Resource not found

 Status: 404 Not Found

Notes

Ping a repository webhook

This will trigger a ping event to be sent to the hook.

post /repos/{owner}/{repo}/hooks/{hook_id}/pings

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/pings
JavaScript (@octokit/core.js)
 await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/pings', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 204 No Content

Resource not found

 Status: 404 Not Found

Notes

Test the push repository webhook

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

post /repos/{owner}/{repo}/hooks/{hook_id}/tests

Parameters

NameTypeInDescription
acceptstringheader

Setting toapplication/vnd.github.v3+json is recommended.

ownerstringpath
repostringpath
hook_idintegerpath

Code samples

Shell
 curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/hooks/42/tests
JavaScript (@octokit/core.js)
 await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/tests', {
  owner: 'octocat',
  repo: 'hello-world',
  hook_id: 42
})

Response

 Status: 204 No Content

Resource not found

 Status: 404 Not Found

Notes