Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment