webhooks

Creates, updates, deletes, gets or lists a webhooks resource.

Overview

Name	webhooks
Type	Resource
Id	github.repos.webhooks

Fields

The following fields are returned by SELECT queries:

get_webhook

Response

Name	Datatype	Description
id	integer	Unique identifier of the webhook.
name	string	The name of a valid service, use 'web' for a webhook. (example: web)
active	boolean	Determines whether the hook is actually triggered on pushes.
config	object	Configuration object of the webhook (title: Webhook Configuration)
created_at	string (date-time)	(example: 2011-09-06T17:26:27Z)
deliveries_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/deliveries)
events	array	Determines what events the hook is triggered for. Default: ['push'].
last_response	object	(title: Hook Response)
ping_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/pings)
test_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/test)
type	string
updated_at	string (date-time)	(example: 2011-09-06T20:39:23Z)
url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1)

list_webhooks

Response

Name	Datatype	Description
id	integer	Unique identifier of the webhook.
name	string	The name of a valid service, use 'web' for a webhook. (example: web)
active	boolean	Determines whether the hook is actually triggered on pushes.
config	object	Configuration object of the webhook (title: Webhook Configuration)
created_at	string (date-time)	(example: 2011-09-06T17:26:27Z)
deliveries_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/deliveries)
events	array	Determines what events the hook is triggered for. Default: ['push'].
last_response	object	(title: Hook Response)
ping_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/pings)
test_url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1/test)
type	string
updated_at	string (date-time)	(example: 2011-09-06T20:39:23Z)
url	string (uri)	(example: https://api.github.com/repos/octocat/Hello-World/hooks/1)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_webhook	select	owner, repo, hook_id		Returns a webhook configured in a repository. To get only the webhook config properties, see "Get a webhook configuration for a repository."
list_webhooks	select	owner, repo	per_page, page	Lists webhooks for a repository. last response may return null if there have not been any deliveries within 30 days.
create_webhook	insert	owner, repo		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.
update_webhook	update	owner, repo, hook_id		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."
delete_webhook	delete	owner, repo, hook_id		Delete a webhook for an organization. The authenticated user must be a repository owner, or have admin access in the repository, to delete the webhook.
ping_webhook	exec	owner, repo, hook_id		This will trigger a ping event to be sent to the hook.
test_push_webhook	exec	owner, repo, hook_id		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

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
hook_id	integer	The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."

SELECT examples

get_webhook

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

SELECT
id,
name,
active,
config,
created_at,
deliveries_url,
events,
last_response,
ping_url,
test_url,
type,
updated_at,
url
FROM github.repos.webhooks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND hook_id = '{{ hook_id }}' -- required
;

list_webhooks

Lists webhooks for a repository. last response may return null if there have not been any deliveries within 30 days.

SELECT
id,
name,
active,
config,
created_at,
deliveries_url,
events,
last_response,
ping_url,
test_url,
type,
updated_at,
url
FROM github.repos.webhooks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

INSERT examples

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

INSERT INTO github.repos.webhooks (
name,
config,
events,
active,
owner,
repo
)
SELECT 
'{{ name }}',
'{{ config }}',
'{{ events }}',
{{ active }},
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
name,
active,
config,
created_at,
deliveries_url,
events,
last_response,
ping_url,
test_url,
type,
updated_at,
url
;

Manifest

# Description fields are for documentation purposes
- name: webhooks
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the webhooks resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the webhooks resource.
  - name: name
    value: "{{ name }}"
    description: |
      Use `web` to create a webhook. Default: `web`. This parameter only accepts the value `web`.
  - name: config
    description: |
      Key/value pairs to provide settings for this webhook.
    value:
      url: "{{ url }}"
      content_type: "{{ content_type }}"
      secret: "{{ secret }}"
      insecure_ssl: "{{ insecure_ssl }}"
  - name: events
    value:
      - "{{ events }}"
    description: |
      Determines what [events](https://docs.github.com/webhooks/event-payloads) the hook is triggered for.
    default: push
  - name: active
    value: {{ active }}
    description: |
      Determines if notifications are sent when the webhook is triggered. Set to `true` to send notifications.
    default: true

UPDATE examples

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

UPDATE github.repos.webhooks
SET 
config = '{{ config }}',
events = '{{ events }}',
add_events = '{{ add_events }}',
remove_events = '{{ remove_events }}',
active = {{ active }}
WHERE 
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND hook_id = '{{ hook_id }}' --required
RETURNING
id,
name,
active,
config,
created_at,
deliveries_url,
events,
last_response,
ping_url,
test_url,
type,
updated_at,
url;

DELETE examples

delete_webhook

Delete a webhook for an organization.

The authenticated user must be a repository owner, or have admin access in the repository, to delete the webhook.

DELETE FROM github.repos.webhooks
WHERE owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND hook_id = '{{ hook_id }}' --required
;

Lifecycle Methods

ping_webhook

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

EXEC github.repos.webhooks.ping_webhook 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@hook_id='{{ hook_id }}' --required
;

test_push_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

EXEC github.repos.webhooks.test_push_webhook 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@hook_id='{{ hook_id }}' --required
;