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
Accept
Header 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.com
orbswinnerton@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
redelivery
attribute is alwaysfalse
, even when the delivery was a redelivery of an already sent webhook. - The
redelivery
filter does not properly filter webhook deliveries that were redelivered. - In order to access the non-truncated request and response payloads, the
Accept
header must be passed asapplication/vnd.github.v3.full+json
. In future versions, this was moved to a?include_payload
query argument.
@bswinnerton Following up on my previous feedback,
I started working around this by fetching the
guid
from the webhook request headers, logging it/attaching it to observability tools, and then using theguid
query param from the index endpoint. This was working great, so I'm pretty sad to see that this server-side filter was removed in the release to GA. It would be top of my list for feature requests!