Webhooks API

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

List webhooks

List all webhooks for an account:

GET /webhooks

States

The following states 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 single 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

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.
event
Required string — The event that will trigger this webhook. Valid values are listed below.
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.
uri
Required string — Publicly accessible URI that ITRP can use to POST http messages to.

Valid Events

Events in ITRP 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 ITRP application or from another application that uses the ITRP API.