Jump to >

WebHook List Resource

Added in 2.5

A resource for managing webhooks.

Webhooks are HTTP-based callbacks. When events are triggered on Review Board (such as a review request being published), a webhook can be configured to make a request to a URL with a payload.

Webhooks can be triggered by the following events:

  • Review requests being published (review_request_published).
  • Review requests being closed (review_request_closed).
  • Reviews being published (review_published).
  • Review replies being published (reply_published).
  • All of the above (*).

The payload that is sent depends on the type of event. Review Board will generate a default payload for each event, or it can be overridden by providing your payload as the custom_content field.

By default, the generated payload will be a JSON payload. This can be changed by setting the encoding field to the appropriate value. Valid encodings are:

  • application/json
  • application/xml
  • application/x-www-form-encoded

Payloads can also be signed with a 128-byte secret given in the secret field. If provided, the payload will be signed with the HMAC algorithm.

Webhooks can apply to all repositories, a select number of repositories, or to no repositories. In the latter case, they will only trigger with attachment-only review requests.

Webhooks are Local Site-dependant. They will only trigger for repositories in the configured local site. If no Local Site is configured, they will apply to review requests without a Local Site. If a webhook is configured to trigger for a specific set of repositories, the webhook and all repositories must be in the same Local Site.

Details

Name webhooks
URI /api/webhooks/
Token Policy ID webhook
HTTP Methods
  • GET - Retrieves the list of webhooks.
  • POST - Creates a new webhook.
Parent Resource Root List Resource
Child Resources
Anonymous Access No

HTTP GET

Retrieves the list of webhooks.

Request Parameters

counts-onlyBoolean If specified, a single count field is returned with the number of results, instead of the results themselves.
max-resultsInteger The maximum number of results to return in this list. By default, this is 25. There is a hard limit of 200; if you need more than 200 results, you will need to make more than one request, using the “next” pagination link.
startInteger The 0-based index of the first result in the list. The start index is usually the previous start index plus the number of previous results. By default, this is 0.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
105 - Invalid Form DataHTTP 400 - Bad Request One or more fields had errors

HTTP POST

Creates a new webhook.

Extra data can be stored on the webhook for later lookup by passing extra_data.key_name=value. The key_name and value can be any valid strings. Passing a blank value will remove the key. The extra_data. prefix is required.

Extra data values supplied will not be used when building the payload of the webhook.

Request Parameters

apply_toOne of all, none, custom Required

What review requests the webhook applies to. This is one of the strings all, none, or custom. In the case of custom, the repositories should be specified in the repositories field.

enabledBoolean Required

Whether or not the webhook is enabled.

encodingOne of application/json, application/xml, application/x-www-form-urlencoded Required

The encoding for the payload. This is one of application/json, application/xml or application/x-www-form-encoded.

eventsString Required

The type of events that trigger the webhook. This should be a list of values separated by commas.

urlString Required

The URL to make HTTP requests against.

custom_contentString An optional custom payload.
repositoriesString If apply_to is selected repositories, this is a comma-separated list of repository IDs that the webhook applies to.
secretString An optional HMAC digest for the webhook payload. If this is specified, the payload will be signed with it.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
105 - Invalid Form DataHTTP 400 - Bad Request One or more fields had errors

Examples

application/vnd.reviewboard.org.webhooks+json

$ curl http://reviews.example.com/api/webhooks/ -H "Accept: application/json"
Vary: Accept, Cookie
Item-Content-Type: application/vnd.reviewboard.org.webhook+json
Content-Type: application/vnd.reviewboard.org.webhooks+json
X-Content-Type-Options: nosniff
{
  "links": {
    "create": {
      "href": "http://reviews.example.com/api/webhooks/", 
      "method": "POST"
    }, 
    "self": {
      "href": "http://reviews.example.com/api/webhooks/", 
      "method": "GET"
    }
  }, 
  "stat": "ok", 
  "total_results": 1, 
  "webhooks": [
    {
      "apply_to": "all", 
      "custom_content": null, 
      "enabled": true, 
      "encoding": "application/json", 
      "events": [
        "*"
      ], 
      "extra_data": {}, 
      "id": 1, 
      "links": {
        "delete": {
          "href": "http://reviews.example.com/api/webhooks/1/", 
          "method": "DELETE"
        }, 
        "self": {
          "href": "http://reviews.example.com/api/webhooks/1/", 
          "method": "GET"
        }, 
        "update": {
          "href": "http://reviews.example.com/api/webhooks/1/", 
          "method": "PUT"
        }
      }, 
      "repositories": [], 
      "secret": "", 
      "url": "http://example.com/webhook"
    }
  ]
}