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	WebHook Resource
Anonymous Access	No

Links¶

Name	Method	Resource
create	POST	WebHook List Resource
self	GET	WebHook List Resource

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