Organisationswebhooks

Verwende die REST-API, um mit Webhooks in einer Organisation zu interagieren.

Informationen zu Organisationswebhooks

Organisationswebhooks ermöglichen es dir, POST-HTTP-Nutzdaten zu empfangen, wenn bestimmte Ereignisse in einer Organisation auftreten. Weitere Informationen findest du unter Informationen zu Webhooks.

Bereiche und Einschränkungen

Alle Aktionen für Organisationswebhooks erfordern, dass der authentifizierte Benutzer ein Administrator der Organisation sein muss, die verwaltet wird. Darüber hinaus benötigen OAuth-Token den admin:org_hook-Bereich. Weitere Informationen findest du unter Bereiche für OAuth-Apps.

Um vertrauliche Daten zu schützen, die in Webhook-Konfigurationen vorhanden sein können, erzwingen wir auch die folgenden Zugriffssteuerungsregeln:

OAuth-Anwendungen können keine Webhooks auflisten, anzeigen oder bearbeiten, die sie nicht erstellt haben.
Benutzer*innen können Webhooks, die von OAuth-Anwendungen erstellt wurden, nicht auflisten, anzeigen oder bearbeiten.

Empfangen von Webhooknutzdaten

Damit GitHub Enterprise Server Webhooknutzlasten senden kann, muss ein Zugriff auf deinen Server über das Internet möglich sein. Zudem wird dringend empfohlen, SSL zu verwenden, sodass verschlüsselte Nutzdaten über HTTPS gesendet werden können.

Weitere Best Practices findest du in unserem Leitfaden.

Webhookheader

GitHub Enterprise Server sendet mehrere HTTP-Header, um zwischen Ereignistypen und Nutzdatenbezeichnern zu unterscheiden. Details findest du unter Webhookheader.

List organization webhooks

Funktioniert mit GitHub Apps

Parameter für „List organization webhooks“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
Abfrageparameter
Name, type, BESCHREIBUNG
`per_page` integer The number of results per page (max 100). Standard: `30`
`page` integer Page number of the results to fetch. Standard: `1`

HTTP-Antwortstatuscodes für „List organization webhooks“

Statuscode	BESCHREIBUNG
`200`	OK
`404`	Resource not found

Codebeispiele für „List organization webhooks“

get/orgs/{org}/hooks

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks

Response

Status: 200

[
  {
    "id": 1,
    "url": "https://HOSTNAME/orgs/octocat/hooks/1",
    "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
    "deliveries_url": "https://HOSTNAME/orgs/octocat/hooks/1/deliveries",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z",
    "type": "Organization"
  }
]

Create an organization webhook

Funktioniert mit GitHub Apps

Here's how you can create a hook that posts payloads in JSON format:

Parameter für „Create an organization webhook“

Header

Name, type, BESCHREIBUNG

accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter

Name, type, BESCHREIBUNG

org string Erforderlich

The organization name. The name is not case sensitive.

Textparameter

Name, type, BESCHREIBUNG

name string Erforderlich

Must be passed as "web".

config object Erforderlich

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

Properties of config

Name, type, BESCHREIBUNG
`url` string Erforderlich 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 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.
`username` string
`password` string

events array of strings

Determines what events the hook is triggered for. Set to ["*"] to receive all possible events.

Standard: ["push"]

active boolean

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

Standard: true

HTTP-Antwortstatuscodes für „Create an organization webhook“

Statuscode	BESCHREIBUNG
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Codebeispiele für „Create an organization webhook“

post/orgs/{org}/hooks

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks \
  -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"http://example.com/webhook","content_type":"json"}}'

Response

Status: 201

{
  "id": 1,
  "url": "https://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/orgs/octocat/hooks/1/deliveries",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Get an organization webhook

Funktioniert mit GitHub Apps

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

Parameter für „Get an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.

HTTP-Antwortstatuscodes für „Get an organization webhook“

Statuscode	BESCHREIBUNG
`200`	OK
`404`	Resource not found

Codebeispiele für „Get an organization webhook“

get/orgs/{org}/hooks/{hook_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID

Response

Status: 200

{
  "id": 1,
  "url": "https://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/orgs/octocat/hooks/1/deliveries",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Update an organization webhook

Funktioniert mit GitHub Apps

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

Parameter für „Update an organization webhook“

Header

Name, type, BESCHREIBUNG

accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter

Name, type, BESCHREIBUNG

org string Erforderlich

The organization name. The name is not case sensitive.

hook_id integer Erforderlich

The unique identifier of the hook.

Textparameter

Name, type, BESCHREIBUNG

config object

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

Properties of config

Name, type, BESCHREIBUNG
`url` string Erforderlich 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 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.

events array of strings

Determines what events the hook is triggered for.

Standard: ["push"]

active boolean

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

Standard: true

name string

HTTP-Antwortstatuscodes für „Update an organization webhook“

Statuscode	BESCHREIBUNG
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Codebeispiele für „Update an organization webhook“

patch/orgs/{org}/hooks/{hook_id}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID \
  -d '{"active":true,"events":["pull_request"]}'

Response

Status: 200

{
  "id": 1,
  "url": "https://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "name": "web",
  "events": [
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Delete an organization webhook

Funktioniert mit GitHub Apps

Parameter für „Delete an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.

HTTP-Antwortstatuscodes für „Delete an organization webhook“

Statuscode	BESCHREIBUNG
`204`	No Content
`404`	Resource not found

Codebeispiele für „Delete an organization webhook“

delete/orgs/{org}/hooks/{hook_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID

Response

Status: 204

Get a webhook configuration for an organization

Funktioniert mit GitHub Apps

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

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:read permission.

Parameter für „Get a webhook configuration for an organization“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.

HTTP-Antwortstatuscodes für „Get a webhook configuration for an organization“

Statuscode	BESCHREIBUNG
`200`	OK

Codebeispiele für „Get a webhook configuration for an organization“

get/orgs/{org}/hooks/{hook_id}/config

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/config

Response

Status: 200

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

Update a webhook configuration for an organization

Funktioniert mit GitHub Apps

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

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:write permission.

Parameter für „Update a webhook configuration for an organization“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.
Textparameter
Name, type, BESCHREIBUNG
`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 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.

HTTP-Antwortstatuscodes für „Update a webhook configuration for an organization“

Statuscode	BESCHREIBUNG
`200`	OK

Codebeispiele für „Update a webhook configuration for an organization“

patch/orgs/{org}/hooks/{hook_id}/config

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/config \
  -d '{"url":"http://example.com/webhook","content_type":"json","insecure_ssl":"0","secret":"********"}'

Response

Status: 200

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

List deliveries for an organization webhook

Funktioniert mit GitHub Apps

Returns a list of webhook deliveries for a webhook configured in an organization.

Parameter für „List deliveries for an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.
Abfrageparameter
Name, type, BESCHREIBUNG
`per_page` integer The number of results per page (max 100). Standard: `30`
`cursor` string 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.
`redelivery` boolean

HTTP-Antwortstatuscodes für „List deliveries for an organization webhook“

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Codebeispiele für „List deliveries for an organization webhook“

get/orgs/{org}/hooks/{hook_id}/deliveries

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries

Response

Status: 200

[
  {
    "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
  }
]

Get a webhook delivery for an organization webhook

Funktioniert mit GitHub Apps

Returns a delivery for a webhook configured in an organization.

Parameter für „Get a webhook delivery for an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.
`delivery_id` integer Erforderlich

HTTP-Antwortstatuscodes für „Get a webhook delivery for an organization webhook“

Statuscode	BESCHREIBUNG
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Codebeispiele für „Get a webhook delivery for an organization webhook“

get/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID

Response

Status: 200

{
  "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"
  }
}

Redeliver a delivery for an organization webhook

Funktioniert mit GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

Parameter für „Redeliver a delivery for an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.
`delivery_id` integer Erforderlich

HTTP-Antwortstatuscodes für „Redeliver a delivery for an organization webhook“

Statuscode	BESCHREIBUNG
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Codebeispiele für „Redeliver a delivery for an organization webhook“

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Status: 202

Ping an organization webhook

Funktioniert mit GitHub Apps

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

Parameter für „Ping an organization webhook“

Header
Name, type, BESCHREIBUNG
`accept` string Setting to `application/vnd.github+json` is recommended.
Pfadparameter
Name, type, BESCHREIBUNG
`org` string Erforderlich The organization name. The name is not case sensitive.
`hook_id` integer Erforderlich The unique identifier of the hook.

HTTP-Antwortstatuscodes für „Ping an organization webhook“

Statuscode	BESCHREIBUNG
`204`	No Content
`404`	Resource not found

Codebeispiele für „Ping an organization webhook“

post/orgs/{org}/hooks/{hook_id}/pings

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204