Webhooks API

Only users with the administrator role are authorized to use this API.

List Webhooks

List all webhooks for an account:

GET /webhooks

Predefined Filters

The following predefined filters are available:

Response

Status: 200 OK
[
  {
    "id": 2,
    "name": "Problem Update",
    "event": "problem.update",
    "uri": "https://myserver.example.com/mywebhook",
    "created_at": "2016-03-17T16:36:11-06:00",
    "updated_at": "2016-03-17T17:09:18-06:00"
  },
  {
    "id": 1,
    "name": "Request Team Changed",
    "event": "request.team-changed",
    "uri": "http://postbin.org/axbxd3",
    "disabled": "true",
    "last_error": "404 Not Found",
    "created_at": "2016-03-17T16:34:59-06:00",
    "updated_at": "2016-03-17T16:34:59-06:00"
  }
]

Get a Webhook

GET /webhooks/:id

Response

Status: 200 OK
{
  "id": 2,
  "name": "problem.update",
  "event": "problem.update",
  "uri": "https://myserver.example.com/mywebhook",
  "description": "Update requests related to the problem by adding a note.",
  "mail_exceptions_to": "webhook.monitor@example.com",
  "created_at": "2016-03-17T16:36:11-06:00",
  "updated_at": "2016-03-17T17:09:18-06:00"
}

Create a Webhook

POST /webhooks

When creating a new webhook these fields are available.

{
  "event": "problem.update",
  "uri": "https://myserver.example.com/mywebhook"
}

Response

Status: 200 OK
{
  "id": 2,
  "name": "problem.update",
  "event": "problem.update",
  "uri": "https://myserver.example.com/mywebhook",
  "description": "Update requests related to the problem by adding a note.",
  "mail_exceptions_to": "webhook.monitor@example.com",
  "created_at": "2016-03-17T16:36:11-06:00",
  "updated_at": "2016-03-17T17:09:18-06:00"
}

Edit a Webhook

PATCH /webhooks/:id

When updating a new webhook these fields are available.

{
  "event": "problem.update",
  "uri": "https://myserver.example.com/mywebhook"
}

Response

Status: 200 OK
{
  "id": 2,
  "name": "problem.update",
  "event": "problem.update",
  "uri": "https://myserver.example.com/mywebhook",
  "description": "Update requests related to the problem by adding a note.",
  "mail_exceptions_to": "webhook.monitor@example.com",
  "created_at": "2016-03-17T16:36:11-06:00",
  "updated_at": "2016-03-17T17:09:18-06:00"
}

Delete a Webhook

DELETE /webhooks/:id

Response

Status: 204 No Content

Test a Webhook

Tests your webhook. You can also test disabled webhooks. When you create a webhook you might want to disable it first, then test until you’re happy, then enable it.

POST /webhooks/:id/test

Response

Status: 204 No Content

In addition your script should receive a POST http request with the webhook contents. The object_id will always be equal to 12345 for these tests.

Fields

attachments
Readonly aggregated Attachments
disabled
Optional boolean — Defaults to false
description
Optional text (max 64KB) — The Description field is used to enter a description of the webhook’s purpose.
description_attachments
Writeonly attachments The attachments used in the Description field.
event
Required string — The event that will trigger this webhook. Valid values are listed below.
id
Readonly integer — The unique ID of the webhook.
mail_exceptions_to
Optional string — Comma separated list of email addresses who will be informed when the webhook execution fails, e.g. john.doe@example.com,jane.doe@example.com.
name
Optional string — The name of this webhook. Defaults to the event name.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
updated_at
Readonly datetime — The date and time of the last update of the webhook. If the webhook has no updates it contains the created_at value.
uri
Required string — Publicly accessible URI that R-Service can use to POST http messages to.
webhook_policy
Optional reference to Webhook Policy — The Webhook Policy field is used to select the policy with which to sign the webhook messages.

Events

Events in R-Service are identified by the combination of a noun and a verb (i.e. request.create). Note that webhooks are notified when these events occur from within the R-Service application or from another application that uses the R-Service API. The automation_rule webhook event type can be used to notify webhooks from within Automation Rules.