The webhook deliveries API has been released on GitHub.com as of June 30, 2021. See the blog post. It will be available in the next major release of GitHub Enterprise Server.
For those who have followed along in this gist - the gist below documented various filters that could be used with the endpoints for Listing Webhook Deliveries. For this first GA release of the webhook deliveries API no server-side filtering is available. We hope to be able to release some filtering capability in the future, but for the time being all information used for filtering is available in the API response and can be used for client-side filtering. Please reach out to GitHub support if you have any issues.
Webhooks are a way for our integrators to be notified of predefined GitHub events. Today, webhooks may fail to be delivered for a variety of reasons: severed connections, downtime from GitHub, downtime from the integrator, etc. Right now, we offer the ability to view failed webhook deliveries in the UI and retry them, but we don’t provide a similar set of functionality in our REST or GraphQL API.
We are introducing a REST API that will allow integrators to query the status of webhook deliveries, and trigger redeliveries where needed.
Note: To access these API endpoints, you must provide a custom media type in the
AcceptHeader for your requests as part of the API preview:
application/vnd.github.starlord-preview+json
NOTE: To access these API endpoints, please contact
andrewholt@github.comorbswinnerton@github.com.
GET /repos/:owner/:repo/hooks/:hook_id/deliveries
GET /orgs/:org/hooks/:hook_id/deliveries
GET /app/hook/deliveries
This endpoint will return all deliveries, irrespective of whether or not they are a redelivery.
| Name | Type | Description |
|---|---|---|
since |
string |
Only deliveries after this datetime will be returned. ISO8601 format: YYYY-MM-DDTHH:MM:SSZ. |
until |
string |
Only deliveries before this datetime will be returned. ISO8601 format: YYYY-MM-DDTHH:MM:SSZ. |
status |
string |
Only deliveries of this status will be returned. Can be one of success, failure. |
status_codes |
array of integers |
Only deliveries which received these status codes will be returned. |
events |
array of strings |
Only deliveries of this event type and action will be returned. Actions can be specified by using the format: <event>.<action> e.g. issue_comment.created. |
redelivery |
boolean |
Either true to return only deliveries which were reattempted, or false to return all deliveries. Default: true. |
guid |
string |
Only deliveries with this guid will be returned. Includes both initial deliveries and reattempted deliveries. |
cursor |
string |
Indicates the starting delivery id from which the next paged will be fetched. Used for pagination |
per_page |
Integer |
Defines the maximum size of records fetched. Used for pagination Max value supported: 100. Defaults to: 30 |
Status: 200 OK[
{
"id": 1,
"guid": "c7f212c0-6389-11e8-9793-903f54742472",
"delivered_at": "2018-05-29T17:46:45Z",
"redelivery": false,
"duration": 0.500,
"status": "success",
"status_code": 204,
"event": "label",
"action": "created",
}
]GET /repos/:owner/:repo/hooks/:hook_id/deliveries/:delivery_id
GET /orgs/:org/hooks/:hook_id/deliveries/:delivery_id
GET /app/hook/deliveries/:delivery_id
The request[payload] and response[payload] attributes return null values by default. To include the contents of the payload, you must pass the include_payload=true query param.
Status: 200 OK{
"id": 1,
"guid": "c7f212c0-6389-11e8-9793-903f54742472",
"delivered_at": "2018-05-29T17:46:45Z",
"redelivery": false,
"duration": 0.500,
"status": "success",
"status_code": 204,
"event": "label",
"action": "created",
"request": {
"truncated": true,
"headers": "{\"Request URL\": \"https://bswinnerton.ngrok.io/api-playground/brooks\", \"Request method\": \"POST\", \"content-type\": \"application/json\", \"Expect\": \"\", \"User-Agent: GitHub-Hookshot/fba5abc\", \"X-GitHub-Delivery\": \"7713d1d0-ce60-11e8-9d82-5955",
"payload": "{ \"action\": \"created\", \"label\": { \"id\": 1089229605, \"node_id\": \"MDU6TGFiZWwxMDg5MjI5NjA1\", \"url\": \"https://api.github.com/repos/api-playground/brooks/labels/kittens\", \"name\": \"kittens\", \"color\": \"bfdadc\", \"default\": false }, \"re"
},
"response": {
"truncated": true,
"headers": "{\"Content-Length\": 0, \"X-Content-Type-Options\": \"nosniff\"}",
"payload": "OK"
}
}POST /repos/:owner/:repo/hooks/:hook_id/deliveries/:delivery_id/attempts
POST /orgs/:org/hooks/:hook_id/deliveries/:delivery_id/attempts
POST /app/hook/deliveries/:delivery_id/attempts
Status: 202 Accepted
These APIs are available to preview immediately in github.com and GitHub Enterprise Cloud, and were added in GHES 3.0.
Once you’ve had a chance to review or integrate with these APIs, we would love to gather your feedback.
- The
redeliveryattribute is alwaysfalse, even when the delivery was a redelivery of an already sent webhook. - The
redeliveryfilter does not properly filter webhook deliveries that were redelivered. - In order to access the non-truncated request and response payloads, the
Acceptheader must be passed asapplication/vnd.github.v3.full+json. In future versions, this was moved to a?include_payloadquery argument.
I am trying to use these endpoints to investigate webhook deliveries, but running into a few limitations:
GET /app/hook/deliveries/:delivery_id, theresponse[payload]is alwaysnull, regardless ofAcceptheader. I've triedapplication/vnd.github.starlord-preview+json,application/vnd.github.v3+json, andapplication/vnd.github.v3.full+json.