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

app_offering_references
Optional array of strings — Available for app_instance events. This webhook will only be triggered when the App Instance has one of the specified App Offering references.
attachments
Readonly aggregated Attachments
created_at
Readonly datetime — The date and time at which the webhook was created.
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 Xurrent can use to POST http messages to.
openid_connect_discovery
Optional boolean, default: false — The OpenID Connect Discovery box is checked when the public key of the webhook policy should be discoverable via the OpenID Connect Discovery protocol. When enabled, the JWT iss (issuer) claim identifies a discovery endpoint from which the public key can be retrieved. See Automatic Key Discovery.
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 Xurrent 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 Xurrent application or from another application that uses the Xurrent API. The automation_rule webhook event type can be used to notify webhooks from within Automation Rules.