Webhooks Web Services

Overview

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

XMLJSON
 XML
<executionUser>
      <username>test</username>
      <password>pass1</password>
</executionUser> 
 JSON
{
 "username": "test",
 "password": "pass1" 
}

Disable a Webhook


 Description

URI

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


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/ops-enable-disable-webhook


HTTP Method

POST

Description

Enables/Disables a list of webhooks.

Example URI

http://localhost:8080/uc/resources/webhook/ops-enable-disable-webhook

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 

PropertyUI Field NameDescription

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


XMLJSON
Example Request
<enable-disable-webhook>
    <webhook enable="true" name="test-1"></webhook>
    <webhook enable="false" name="test-3"></webhook>
</enable-disable-webhook> 
 [{
     "enable": true,
     "name": "test-1"
  },
  {
     "enable": false,
     "name": "test-3"
  }]
Example Response
<command-response>
    <type>Enable/Disable Webhooks</type>
    <success>true</success>
    <info>Successfully disabled Webhook "test-3"., Successfully enabled Webhook "test-1".</info>
    <errors></errors>
</command-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

List Webhooks: Example Response

XMLJSON
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<webhooks>
    <webhook exportReleaseLevel="7.4.0.0" exportTable="ops_webhook">
        <action>Url</action>
        <credentials>web-serv-1</credentials>
        <description />
        <disabledBy>ops.admin</disabledBy>
        <disabledTime>2023-03-15 15:34:24 -0400</disabledTime>
        <enabledBy></enabledBy>
        <enabledTime></enabledTime>
        <event label="UAC - Agent Changed">uac_agent_changed</event>
        <executionUser />
        <filter>
            <criterion>
                <name>name</name>
                <operator>CONTAINS</operator>
                <value>test1</value>
            </criterion>
            <logicalOperator>And</logicalOperator>
        </filter>
        <httpAuth>Basic</httpAuth>
        <httpHeaders>
            <httpHeader>
                <name>B</name>
                <value>123</value>
            </httpHeader>
        </httpHeaders>
        <name>test-1</name>
        <opswiseGroups>
            <opswiseGroup>A</opswiseGroup>
        </opswiseGroups>
        <status>Disabled</status>
        <statusDescription></statusDescription>
        <sysId>401b83365dcd48cf8a8518849dfb28c4</sysId>
        <taskname />
        <url>test</url>
        <urlParameters>
            <urlParameter>
                <name>A</name>
                <value>abc</value>
            </urlParameter>
        </urlParameters>
    </webhook>
    <webhook exportReleaseLevel="7.4.0.0" exportTable="ops_webhook">
        <action>Url</action>
        <credentials>web-serv-1</credentials>
        <description />
        <disabledBy>ops.admin</disabledBy>
        <disabledTime>2023-03-15 14:00:59 -0400</disabledTime>
        <enabledBy></enabledBy>
        <enabledTime></enabledTime>
        <event label="UAC - Agent Changed">uac_agent_changed</event>
        <executionUser />
        <filter>
            <criterion>
                <name>name</name>
                <operator>CONTAINS</operator>
                <value>test1</value>
            </criterion>
            <logicalOperator>And</logicalOperator>
        </filter>
        <httpAuth>Basic</httpAuth>
        <httpHeaders>
            <httpHeader>
                <name>X</name>
                <value>123</value>
            </httpHeader>
        </httpHeaders>
        <name>test-2</name>
        <opswiseGroups/>
        <status>Disabled</status>
        <statusDescription></statusDescription>
        <sysId>bb0bf1ae08cb4ac3a8df69bc5548281c</sysId>
        <taskname />
        <url>test</url>
        <urlParameters>
            <urlParameter>
                <name>A</name>
                <value>abc</value>
            </urlParameter>
        </urlParameters>
    </webhook>
</webhooks>
 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"
        },
        "executionUser": null,
        "exportReleaseLevel": "7.4.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",
        "taskname": 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"
        },
        "executionUser": null,
        "exportReleaseLevel": "7.4.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",
        "taskname": 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 PropertiesSee 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

XMLJSON
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<webhook exportReleaseLevel="7.4.0.0" exportTable="ops_webhook" retainSysIds="true">
    <action>Launch Task</action>
    <description>test 1</description>
    <disabledBy />
    <disabledTime></disabledTime>
    <enabledBy />
    <enabledTime></enabledTime>
    <event label="UAC - Property Changed">uac_property_changed</event>
    <executionUser />
    <filter>
        <criterion>
            <name>name</name>
            <operator>CONTAINS</operator>
            <value>Suspended</value>
        </criterion>
        <logicalOperator>And</logicalOperator>
    </filter>
    <name>test-1</name>
    <opswiseGroups>
        <opswiseGroup>A</opswiseGroup>
        <opswiseGroup>B</opswiseGroup>
    </opswiseGroups>
    <status />
    <sysId>63eacfe0b0534768ab7b5bef49212276</sysId>
    <taskname>Sleep 0</taskname>
    <url />
</webhook>
 JSON
{
    "action": "Launch Task",
    "description": "test 1",
    "disabledBy": null,
    "disabledTime": "",
    "enabledBy": null,
    "enabledTime": "",
    "event": {
        "label": "UAC - Property Changed",
        "value": "uac_property_changed"
    },
    "executionUser": null,
    "exportReleaseLevel": "7.4.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",
    "taskname": "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

n/a

Consumes Content-Type

application/xml, application/json

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

XMLJSON
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<webhook exportReleaseLevel="7.4.0.0" exportTable="ops_webhook" retainSysIds="true">
    <action>Url</action>
    <credentials>web-serv-1</credentials>
    <description />
    <disabledBy>ops.admin</disabledBy>
    <disabledTime>2023-03-15 15:34:24 -0400</disabledTime>
    <enabledBy></enabledBy>
    <enabledTime></enabledTime>
    <event label="UAC - Agent Changed">uac_agent_changed</event>
    <executionUser />
    <filter>
        <criterion>
            <name>name</name>
            <operator>CONTAINS</operator>
            <value>test1</value>
        </criterion>
        <logicalOperator>And</logicalOperator>
    </filter>
    <httpAuth>Basic</httpAuth>
    <httpHeaders>
        <httpHeader>
            <name>B</name>
            <value>123</value>
        </httpHeader>
    </httpHeaders>
    <name>test-1</name>
    <opswiseGroups>
        <opswiseGroup>A</opswiseGroup>
    </opswiseGroups>
    <status>Disabled</status>
    <statusDescription></statusDescription>
    <sysId>401b83365dcd48cf8a8518849dfb28c4</sysId>
    <taskname />
    <url>test</url>
    <urlParameters>
        <urlParameter>
            <name>A</name>
            <value>abc</value>
        </urlParameter>
    </urlParameters>
</webhook>
 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"
    },
    "executionUser": null,
    "exportReleaseLevel": "7.4.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",
    "taskname": 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 RequestSee 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"

}

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

filter

Event Criteria

Universal Event criteria to to execute the webhook.


N

url

URL

full URL of the action to be executed. (Including parameters)


Y

(if action
= Url)

taskname

Task

Task of the action to be executed. (Including parameters)


Y

(if action
= Launch Taskl)

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

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

credentials

Credentials

Credentials to be used to authenticate


N

Register a Webhook: Example Request

XML RequestJSON Request
 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<webhook exportReleaseLevel="7.4.0.0" exportTable="ops_webhook" retainSysIds="true">
    <action>Url</action>
    <credentials>web-serv-1</credentials>
    <description />
    <disabledBy>ops.admin</disabledBy>
    <disabledTime>2023-03-15 15:34:24 -0400</disabledTime>
    <enabledBy></enabledBy>
    <enabledTime></enabledTime>
    <event label="UAC - Agent Changed">uac_agent_changed</event>
    <executionUser />
    <filter>
        <criterion>
            <name>name</name>
            <operator>CONTAINS</operator>
            <value>test1</value>
        </criterion>
        <logicalOperator>And</logicalOperator>
    </filter>
    <httpAuth>Basic</httpAuth>
    <httpHeaders>
        <httpHeader>
            <name>B</name>
            <value>123</value>
        </httpHeader>
    </httpHeaders>
    <name>test-1</name>
    <opswiseGroups>
        <opswiseGroup>A</opswiseGroup>
    </opswiseGroups>
    <status>Disabled</status>
    <statusDescription></statusDescription>
    <sysId>401b83365dcd48cf8a8518849dfb28c4</sysId>
    <taskname />
    <url>test</url>
    <urlParameters>
        <urlParameter>
            <name>A</name>
            <value>abc</value>
        </urlParameter>
    </urlParameters>
</webhook>
 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"
    },
    "executionUser": null,
    "exportReleaseLevel": "7.4.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",
    "taskname": 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