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
Parameter für „List organization webhooks“
Header |
---|
Name, type, BESCHREIBUNG |
accept string Setting to |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
Abfrageparameter |
Name, type, BESCHREIBUNG |
per_page integer The number of results per page (max 100). Standard: |
page integer Page number of the results to fetch. Standard: |
HTTP-Antwortstatuscodes für „List organization webhooks“
Statuscode | BESCHREIBUNG |
---|---|
200 | OK |
404 | Resource not found |
Codebeispiele für „List organization webhooks“
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
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 | ||||||||||
Pfadparameter | ||||||||||
Name, type, BESCHREIBUNG | ||||||||||
org string ErforderlichThe organization name. The name is not case sensitive. | ||||||||||
Textparameter | ||||||||||
Name, type, BESCHREIBUNG | ||||||||||
name string ErforderlichMust be passed as "web". | ||||||||||
config object ErforderlichKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||||
Properties of |
Name, type, BESCHREIBUNG |
---|
url string ErforderlichThe URL to which the payloads will be delivered. |
content_type string The media type used to serialize the payloads. Supported values include |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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
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 | ||||||||
Pfadparameter | ||||||||
Name, type, BESCHREIBUNG | ||||||||
org string ErforderlichThe organization name. The name is not case sensitive. | ||||||||
hook_id integer ErforderlichThe 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 |
Name, type, BESCHREIBUNG |
---|
url string ErforderlichThe URL to which the payloads will be delivered. |
content_type string The media type used to serialize the payloads. Supported values include |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
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“
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
Parameter für „Delete an organization webhook“
Header |
---|
Name, type, BESCHREIBUNG |
accept string Setting to |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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 |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe unique identifier of the hook. |
Abfrageparameter |
Name, type, BESCHREIBUNG |
per_page integer The number of results per page (max 100). Standard: |
cursor string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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
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 |
Pfadparameter |
Name, type, BESCHREIBUNG |
org string ErforderlichThe organization name. The name is not case sensitive. |
hook_id integer ErforderlichThe 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“
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