Jump to >

WebHook 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 webhook
URI /api/webhooks/{webhook_id}/
Token Policy ID webhook
HTTP Methods
  • DELETE - Deletes a webhook.
  • GET - Retrieves information about a webhook.
  • PUT - Updates a webhook.
Parent Resource WebHook List Resource
Child Resources None
Anonymous Access No

Fields

apply_toOne of all, none, custom What review requests the webhook applies to. This is one of the strings all, none, or custom. In the case of custom, the repositories are specified in the repositories field.
custom_contentString An optional custom payload.
enabledBoolean Whether or not the webhook is enabled.
encodingOne of application/json, application/xml, application/x-www-form-urlencoded The encoding for the payload. This is one of application/json, application/xml or application/x-www-form-data.
eventsList of String A list of events that will cause the webhook to trigger.
extra_dataDictionary Extra data as part of the webhook. This can be set by the API or extensions.
idInteger The numeric ID of the webhook.
repositoriesList of Repository Resource The list of repositories this applies to.
secretString An optional HMAC digest for the webhook payload. If this is specified, the payload will be signed with it.
urlString The URL to make HTTP requests against.

HTTP DELETE

Deletes a webhook.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

HTTP GET

Retrieves information about a webhook.

This endpoint will retrieve all information pertaining to the requested webhook.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

HTTP PUT

Updates a webhook.

Extra data can be stored later lookup. See Storing/Accessing Extra Data for more information.

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

Request Parameters

apply_toOne of all, none, custom 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.
custom_contentString An optional custom payload.
enabledBoolean Whether or not the webhook is enabled.
encodingOne of application/json, application/xml, application/x-www-form-urlencoded The encoding for the payload. This is one of application/json, application/xml or application/x-www-form-encoded.
eventsString The type of events that trigger the webhook. This should be a list of values separated by commas.
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.
urlString The URL to make HTTP requests against.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

Examples

application/vnd.reviewboard.org.webhook+json

$ curl http://reviews.example.com/api/webhooks/1/ -H "Accept: application/json"
Vary: Accept, Cookie
ETag: f205442708f725e27519eb8fa03d27ac91e8981e
Content-Type: application/vnd.reviewboard.org.webhook+json
X-Content-Type-Options: nosniff
{
  "stat": "ok", 
  "webhook": {
    "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"
  }
}