webhooks

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

Overview

Name	webhooks
Type	Resource
Id	github.orgs.webhooks

Fields

The following fields are returned by SELECT queries:

get_webhook

Response

Name	Datatype	Description
id	integer
name	string	(example: web)
active	boolean
config	object
created_at	string (date-time)	(example: 2011-09-06T17:26:27Z)
deliveries_url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1/deliveries)
events	array
ping_url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1/pings)
type	string
updated_at	string (date-time)	(example: 2011-09-06T20:39:23Z)
url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1)

list_webhooks

Response

Name	Datatype	Description
id	integer
name	string	(example: web)
active	boolean
config	object
created_at	string (date-time)	(example: 2011-09-06T17:26:27Z)
deliveries_url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1/deliveries)
events	array
ping_url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1/pings)
type	string
updated_at	string (date-time)	(example: 2011-09-06T20:39:23Z)
url	string (uri)	(example: https://api.github.com/orgs/octocat/hooks/1)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_webhook	select	org, hook_id		Returns a webhook configured in an organization. To get only the webhook config properties, see "Get a webhook configuration for an organization. You must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
list_webhooks	select	org	per_page, page	List webhooks for an organization. The authenticated user must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
create_webhook	insert	org, name, config		Create a hook that posts payloads in JSON format. You must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
update_webhook	update	org, hook_id		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". You must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
delete_webhook	delete	org, hook_id		Delete a webhook for an organization. The authenticated user must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.
ping_webhook	exec	org, hook_id		This will trigger a ping event to be sent to the hook. You must be an organization owner to use this endpoint. OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

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.
org	string	The organization name. 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 an organization. To get only the webhook
config properties, see "Get a webhook configuration for an organization.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

SELECT
id,
name,
active,
config,
created_at,
deliveries_url,
events,
ping_url,
type,
updated_at,
url
FROM github.orgs.webhooks
WHERE org = '{{ org }}' -- required
AND hook_id = '{{ hook_id }}' -- required
;

list_webhooks

List webhooks for an organization.

The authenticated user must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

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

INSERT examples

create_webhook

Create a hook that posts payloads in JSON format.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or
edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

INSERT INTO github.orgs.webhooks (
name,
config,
events,
active,
org
)
SELECT 
'{{ name }}' /* required */,
'{{ config }}' /* required */,
'{{ events }}',
{{ active }},
'{{ org }}'
RETURNING
id,
name,
active,
config,
created_at,
deliveries_url,
events,
ping_url,
type,
updated_at,
url
;

Manifest

# Description fields are for documentation purposes
- name: webhooks
props:
  - name: org
    value: "{{ org }}"
    description: Required parameter for the webhooks resource.
  - name: name
    value: "{{ name }}"
    description: |
      Must be passed as "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 }}"
      username: "{{ username }}"
      password: "{{ password }}"
  - name: events
    value:
      - "{{ events }}"
    description: |
      Determines what [events](https://docs.github.com/webhooks/event-payloads) the hook is triggered for. Set to `["*"]` to receive all possible events.
    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 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".

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

UPDATE github.orgs.webhooks
SET 
config = '{{ config }}',
events = '{{ events }}',
active = {{ active }},
name = '{{ name }}'
WHERE 
org = '{{ org }}' --required
AND hook_id = '{{ hook_id }}' --required
RETURNING
id,
name,
active,
config,
created_at,
deliveries_url,
events,
ping_url,
type,
updated_at,
url;

DELETE examples

delete_webhook

Delete a webhook for an organization.

The authenticated user must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

DELETE FROM github.orgs.webhooks
WHERE org = '{{ org }}' --required
AND hook_id = '{{ hook_id }}' --required
;

Lifecycle Methods

ping_webhook

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

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit
webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

EXEC github.orgs.webhooks.ping_webhook 
@org='{{ org }}' --required, 
@hook_id='{{ hook_id }}' --required
;