github-redeliveries-api.md

Background

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.

Change

We are introducing a REST API that will allow integrators to query the status of webhook deliveries, and trigger redeliveries where needed.

Webhook Deliveries & Redeliveries REST API

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 or bswinnerton@github.com.

1. Get all deliveries
2. Get a single delivery
3. Create a new delivery attempt

Get all deliveries

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.

Parameters

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

Response

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 a single delivery

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

Response

The request[headers], request[payload], response[headers], and response[payload] attributes are truncated at 256 characters. To request the full size of the attributes, you must pass the application/vnd.github.v3.full+json header.

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

Create a new delivery attempt

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

Response

Status: 202 Accepted

Timeline

These APIs are available to preview immediately in github.com and GitHub Enterprise Cloud, but not yet enabled in GitHub Enterprise Server.

Next Steps

Once you’ve had a chance to review or integrate with these APIs, we would love to gather your feedback.