Skip to main content

Webhooks Web Services

Universal Controller supports the following RESTful-based web services for Webhooks operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.

Assign an Execution User to a Webhook​

Description

URI

http://host_name/uc/resources/webhook/assignexecutionuser

HTTP Method

POST

Description

Assigns an Execution User to the specified webhook.

Example URI

http://localhost:8080/uc/resources/webhook/assignexecutionuser?webhookid=

http://localhost:8080/uc/resources/webhook/assignExecutionUser?webhookname=

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Assign an Execution User to a Webhook: Example Request.

Example Response

  • Status 200 /OK
    Successfully assigned execution user "test" to webhook "testWebhook".
  • Status 404 /Not Found
    Assign Execution User failed. You must provide an execution user.

Assign an Execution User to a Webhook: Payload Properties​

Property

UI Field Name

Description

Specifications

Required

password

n/a

If the user executing this web service does not have the ops_admin role; Password of the Execution User.

Y

username

n/a

Name of the Execution User.

Wildcards are supported.

Y

Assign an Execution User to a Webhook: Example Request​

JSON
{
 "username": "test",
 "password": "pass1" 
}

Disable a Webhook​

Description

URI

http://host_name/uc/resources/webhook/disable

HTTP Method

POST

Description

Disables a webhook.

Example URI

http://localhost:8080/uc/resources/webhook/disable

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Request

http://localhost:9090/uc/resources/webhook/disable?webhookname=

http://localhost:9090/uc/resources/webhook/disable?webhookid=

Example Response

See Enable/Disable a Webhook: XML and JSON Examples.

Disable a Webhook: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

webhookid

ID used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookname
is specified)

webhookname

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookid
is specified)

webhookid

Enable a Webhook​

Description

URI

http://host_name/uc/resources/webhook/enable

HTTP Method

POST

Description

Enables a webhook.

Example URI

http://localhost:8080/uc/resources/webhook/enable

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Request

http://localhost:9090/uc/resources/webhook/enable?webhookname=

http://localhost:9090/uc/resources/webhook/enable?webhookid=

Example Response

See Enable/Disable a Webhook: XML and JSON Examples.

Enable a Webhook: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

webhookid

ID used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookname
is specified)

webhookname

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookid
is specified)

webhookid

Enable/Disable Webhooks​

Description

URI

http://host_name/uc/resources/webhook/enabledisable

HTTP Method

POST

Description

Enables/Disables a list of webhooks.

Example URI

http://localhost:8080/uc/resources/webhook/enabledisable

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See Enable/Disable a Webhook: XML and JSON Examples.

Example Response

See Enable/Disable a Webhook: XML and JSON Examples.

Enable/Disable Webhooks: Payload Properties​

Property

UI Field Name

Description

webhook

n/a

There are two attributes for this property:

  • enable: Indication of whether to enable or disable the webhook. Only enabled webhooks are processed by the Controller. Boolean; Valid values: true/false.
  • name: Name used within the Controller to identify this webhook. Maximum of 100 alphanumerics.

For example: <webhook enable="true" name="test-1"></webhook>

Enable/Disable a Webhook: XML and JSON Examples​

Example Request​

[{
     "enable": true,
     "name": "test-1"
  },
  {
     "enable": false,
     "name": "test-3"
  }]

Example Response​

{
    "type": "Enable/Disable Webhooks",
    "success": true,
    "info": "Successfully disabled Webhook \"test-3\"., Successfully enabled Webhook \"test-1\".",
    "errors": ""
}

List Webhooks​

Description

URI

http://host_name/uc/resources/webhook/list

HTTP Method

GET

Description

List webhook registrations.

Example URI

http://localhost:8080/uc/resources/webhook/list?webhookname=

http://localhost:8080/uc/resources/webhook/list?action=

http://localhost:8080/uc/resources/webhook/list?description=

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Consumes Content-Type

n/a

Example Responses

List Webhook: XML and JSON Examples.

List Webhooks: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

N

description

Description

User-defined; description of this record.

String; URI parameter.

N

action

Action

Type of Action.

String; URI parameter.

N

businessServices

Member of Business Services

Business Services that this record belongs to.

String; URI parameter.

N

event

Event

Event name.

String; URI parameter.

N

taskname

Task

Task name.

String; URI parameter.

N

url

URL

URL.

String; URI parameter.

N

List Webhooks: Example Response​

JSON
[
    {
        "action": "Url",
        "credentials": "web-serv-1",
        "description": null,
        "disabledBy": "ops.admin",
        "disabledTime": "2023-03-15 15:34:24 -0400",
        "enabledBy": "",
        "enabledTime": "",
        "event": {
            "label": "UAC - Agent Changed",
            "value": "uac_agent_changed"
        },
        "eventBusinessServiceCriteria": "Member of Specific Business Services or Unassigned",
        "eventBusinessServices": [
        "X",
        "Y",
        "Z"
    ],
        "executionUser": null,
        "exportReleaseLevel": "8.0.0.0",
        "exportTable": "ops_webhook",
        "filter": {
            "criteria": [
                {
                    "type": "criterion",
                    "name": "name",
                    "operator": "CONTAINS",
                    "value": "test1"
                }
            ],
            "logicalOperator": "And"
        },
        "httpAuth": "Basic",
        "httpHeaders": [
            {
                "name": "B",
                "value": "123"
            }
        ],
        "name": "test-1",
        "opswiseGroups": [
            "A"
        ],
        "status": "Disabled",
        "statusDescription": "",
        "sysId": "401b83365dcd48cf8a8518849dfb28c4",
        "task": null,
        "url": "test",
        "urlParameters": [
            {
                "name": "A",
                "value": "abc"
            }
        ]
    },
    {
        "action": "Url",
        "credentials": "web-serv-1",
        "description": null,
        "disabledBy": "ops.admin",
        "disabledTime": "2023-03-15 14:00:59 -0400",
        "enabledBy": "",
        "enabledTime": "",
        "event": {
            "label": "UAC - Agent Changed",
            "value": "uac_agent_changed"
        },
    "eventBusinessServiceCriteria": "Member of Specific Business Services or Unassigned",
    "eventBusinessServices": [
        "X",
        "Y",
        "Z"
    ],
        "executionUser": null,
        "exportReleaseLevel": "8.0.0.0",
        "exportTable": "ops_webhook",
        "filter": {
            "criteria": [
                {
                    "type": "criterion",
                    "name": "name",
                    "operator": "CONTAINS",
                    "value": "test1"
                }
            ],
            "logicalOperator": "And"
        },
        "httpAuth": "Basic",
        "httpHeaders": [
            {
                "name": "X",
                "value": "123"
            }
        ],
        "name": "test-2",
        "opswiseGroups": [],
        "status": "Disabled",
        "statusDescription": "",
        "sysId": "bb0bf1ae08cb4ac3a8df69bc5548281c",
        "task": null,
        "url": "test",
        "urlParameters": [
            {
                "name": "A",
                "value": "abc"
            }
        ]
    }
]

Modify Webhooks​

Description

URI

http://host_name/uc/resources/webhook

HTTP Method

PUT

Description

Modify a webhook.

Example URI

http://localhost:8080/uc/resources/webhook

Authentication

HTTP Basic

Payload Properties

See Register a Webhook: Payload Properties.

Produces Content-Type

application/xml, application/json

Consumes Content-Type

application/xml, application/json

Example Responses

  • Status 200
    • Successfully updated the resourcename with id {uuid}.
  • Status 400
    • Error message.
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • A resourcename with name “{name}” does not exist.
    • A resourcename with id "{uuid}" does not exist.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Modify Webhooks: Example Request​

JSON
{
    "action": "Launch Task",
    "description": "test 1",
    "disabledBy": null,
    "disabledTime": "",
    "enabledBy": null,
    "enabledTime": "",
    "event": {
        "label": "UAC - Property Changed",
        "value": "uac_property_changed"
    },
    "eventBusinessServiceCriteria": "Member of Specific Business Services or Unassigned",
    "eventBusinessServices": [
        "X",
        "Y",
        "Z"
    ],
    "executionUser": null,
    "exportReleaseLevel": "8.0.0.0",
    "exportTable": "ops_webhook",
    "filter": {
        "criteria": [
            {
                "type": "criterion",
                "name": "name",
                "operator": "CONTAINS",
                "value": "Suspended"
            }
        ],
        "logicalOperator": "And"
    },
    "name": "test-1",
    "opswiseGroups": [
        "A",
        "B"
    ],
    "retainSysIds": true,
    "status": null,
    "sysId": "63eacfe0b0534768ab7b5bef49212276",
    "task": "Sleep 0",
    "url": null
}

Read a Webhook​

Description

URI

http://host_name/uc/resources/webhook

HTTP Method

GET

Description

Read webhook registration.

Example URI

http://localhost:8080/uc/resources/webhook?webhookid=

http://localhost:8080/uc/resources/webhook?webhookname=

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Consumes Content-Type

n/a

Example Responses

See Read a Webhook: Example Response, below.

Read a Webhook: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

webhookid

ID used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookname
is specified)

webhookname

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookid
is specified)

webhookid

Read a Webhook: Example Response​

JSON
{
    "action": "Url",
    "credentials": "web-serv-1",
    "description": null,
    "disabledBy": "ops.admin",
    "disabledTime": "2023-03-15 15:34:24 -0400",
    "enabledBy": "",
    "enabledTime": "",
    "event": {
        "label": "UAC - Agent Changed",
        "value": "uac_agent_changed"
    },
    "eventBusinessServiceCriteria": "Member of Specific Business Services or Unassigned",
    "eventBusinessServices": [
        "X",
        "Y",
        "Z"
    ],
    "executionUser": null,
    "exportReleaseLevel": "8.0.0.0",
    "exportTable": "ops_webhook",
    "filter": {
        "criteria": [
            {
                "type": "criterion",
                "name": "name",
                "operator": "CONTAINS",
                "value": "test1"
            }
        ],
        "logicalOperator": "And"
    },
    "httpAuth": "Basic",
    "httpHeaders": [
        {
            "name": "B",
            "value": "123"
        }
    ],
    "name": "test-1",
    "opswiseGroups": [
        "A"
    ],
    "retainSysIds": true,
    "status": "Disabled",
    "statusDescription": "",
    "sysId": "401b83365dcd48cf8a8518849dfb28c4",
    "task": null,
    "url": "test",
    "urlParameters": [
        {
            "name": "A",
            "value": "abc"
        }
    ]
}

Register a Webhook​

Description

URI

http://host_name/uc/resources/webhook

HTTP Method

POST

Description

Register a webhook.

Example URI

http://localhost:8080/uc/resources/webhook

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Consumes Content-Type

application/xml, application/json

Example Request

See Register a Webhook: Example Request, below.

Example Responses

  • Status 200
    • Successfully created the webhook with id {uuid}.
  • Status 400
    • Error message.
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • A webhook with name “{name}” does not exist.
    • A webhook with id "{uuid}" does not exist.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Register a Webhook: Payload Properties​

Property

UI Field Name

Description

Specifications

Required

name

Webhook Name

Name of the Webhook.

Y

description

Description

User-defined; description of this record.

N

opswiseGroups

Member of Business Services

Business Services that this record belongs to.

XML
<opswiseGroups>
      <opswiseGroup>group1</opswiseGroup>
      <opswiseGroup>group2</opswiseGroup>
</opswiseGroups>
JSON
"opswiseGroups": ["group1","group2"]

N

retainSysIds

n/a

Specification for whether or not the Create a Webhook web service will persist the sysId property.

  • If retainSysIds="true" and sysId is included in the request/response, sysId will be persisted to the database.
  • If retainSysIds="false" and sysId is included in the request/response, sysId will be ignored; it will be autogenerated by the Controller.

Note

In XML web services, retainSysIds is specified as an attribute in the <webhook> element.

Valid values: true/false (default is true).

N

action

Action

Type of Action to perform

Valid Values:

  • As String = URL, As Value = 1
  • As String = Launch Task, As Value = 2

Default is URL (1).

Y

event

Event

Universal Event Template name.

XML
<event label="Test Event A">test_event_a</event>
JSON
"event": {
    "label": "Test Event A",
    "value": "test_event_a"
}
info

Only system level event templates will be allowed.

The label is included when reading a Webhook; however, it is ignored when creating/updating a Webhook.

Y

url

URL

If action is URL; Full URL to be invoked. (Including parameters)

Y

(if action
= Url)

task

Task

If action is Launch Task; Task to be launched.

Y

(if action
= Launch Task)

httpAuth

HTTP Authentication

HTTP authentication scheme to use.

Valid values:

  • As String = None, As Value = 0
  • As String = Basic, As Value = 1

Default is None (0).

N

credentials

Credentials

Credentials to be used to authenticate.

N

httpHeaders

HTTP Headers

HTTP headers.

Format:

<httpHeaders>
	<httpHeader>
		<name>header1</name>
		<value>val1</value>
	</httpHeader>
	<httpHeader>
		<name>header2</name>
		<value>val2</value>
	</httpHeader>
</httpHeaders>

N

urlParameters

URL Query Parameters

Any query parameters to be encoded as a query string and appended to the URL.

Format:

<urlParameters>
      <urlParameter>
            <name>param1</name>
            <value>value1</value>
      </urlParameter>
      <urlParameter>
            <name>param2</name>
            <value>value2</value>
      </urlParameter>
</urlParameters>

N

filter

Event Attribute Criteria

Universal Event criteria to execute the Webhook.

N

eventBusinessServiceCriteria

Event Business Service Criteria

Specifies the type of business service filtering to apply when monitoring on Universal Events.

Valid values (case-insensitive):

  • As String = Member of Any Business Service or Unassigned, As Value = 1
  • As String = Member of Specific Business Services or Unassigned, As Value = 2
  • As String = Member of Specific Business Services, As Value = 3
  • As String = Unassigned, As Value = 4

Default is Member of Any Business Service or Unassigned (1).

N

eventBusinessServices

Event Member of Business Services

Specifies one or more business services to filter on when Event Business Service Criteria is one of the following.

  • Member of Specific Business Services or Unassigned
  • Member of Specific Business Services

Format:

XML
<eventBusinessServices>
    <businessService>A</businessService>
    <businessService>B</businessService>
</eventBusinessServices>
JSON
"eventBusinessServices": [
  "A,
  "B"
]

Register a Webhook: Example Request​

JSON
{
    "action": "Url",
    "credentials": "web-serv-1",
    "description": null,
    "disabledBy": "ops.admin",
    "disabledTime": "2023-03-15 15:34:24 -0400",
    "enabledBy": "",
    "enabledTime": "",
    "event": {
        "label": "UAC - Agent Changed",
        "value": "uac_agent_changed"
    },
    "eventBusinessServiceCriteria": "Member of Specific Business Services or Unassigned",
    "eventBusinessServices": [
        "X",
        "Y",
        "Z"
    ],
    "executionUser": null,
    "exportReleaseLevel": "8.0.0.0",
    "exportTable": "ops_webhook",
    "filter": {
        "criteria": [
            {
                "type": "criterion",
                "name": "name",
                "operator": "CONTAINS",
                "value": "test1"
            }
        ],
        "logicalOperator": "And"
    },
    "httpAuth": "Basic",
    "httpHeaders": [
        {
            "name": "B",
            "value": "123"
        }
    ],
    "name": "test-1",
    "opswiseGroups": [
        "A"
    ],
    "retainSysIds": true,
    "status": "Disabled",
    "statusDescription": "",
    "sysId": "401b83365dcd48cf8a8518849dfb28c4",
    "task": null,
    "url": "test",
    "urlParameters": [
        {
            "name": "A",
            "value": "abc"
        }
    ]
}

Unassign an Execution User from a Webhook​

Description

URI

http://host_name/uc/resources/webhook/unassignexecutionuser

HTTP Method

POST

Description

Unassigns an Execution User to the specified webhook.

Example URI

http://localhost:8080/uc/resources/webhook/unassignexecutionuser?webhookid=

http://localhost:8080/uc/resources/webhook/unassignExecutionUser?webhookname=

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Response

  • Status 200 /OK
    Successfully unassigned execution user "test" to webhook "testWebhook".

Unassign an Execution User from a Webhook: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

webhookid

ID used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookname
is specified)

webhookname

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookid
is specified)

webhookid

Unregister a Webhook​

Description

URI

http://host_name/uc/resources/webhook

HTTP Method

DELETE

Description

Unregister a webhook.

Example URI

http://localhost:8080/uc/resources/webhook?webhookname=

http://localhost:8080/uc/resources/webhook?webhookid=

Authentication

HTTP Basic

Example Responses

Webhook deleted successfully.

Unregister a Webhook: Query Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

webhookid

ID used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookname
is specified)

webhookname

webhookname

Name

Name used within the Controller to identify this webhook.

String; URI parameter.

Y
(unless webhookid
is specified)

webhookid