EXECUTE Endpoint

You can execute a webhook, invoking the Action that the webhook is configured to execute, with data given in the request.

The details of the Method, Request Body, and Headers to execute the Execute Webhook API are as shown:

Base URL

https://{tenant url}/api/rest/Webhooks/Execute?extension={endpoint extension}

Note: The endpoint extension is case-sensitive.

Method

POST
Header Name Authorization: REST API Key

Request Body
Key Value
Value Format Value
Body

Text (JSON or XML)

 

 

 

The body of the request, for example, the data to be provided to the configured Action.

Note: The Body parameter in the request is limited to a maximum length of 100,000 characters.

 

 

Here is an example demonstrating how a webhook can be executed using the Rest API. For this example, we assume that a webhook has been configured with an Endpoint Extension value of MyTestWebhook. The Action that the webhook is configured to execute should have a variable called WebhookBody as part of the Update Variables and Stored Values block.

URL

https://{tenant url}/api/rest/Webhooks/Execute?extension=MyTestWebhook

Method

POST
Header Name Authorization: REST API Key

Request Body
Key Value
Value Format Value
Body Text (JSON or XML)

{

“someData”:“someDataValue”,

“otherData”:“otherDataValue”

}

 

For XML, you need a parent node, such as WebhookBody, so the Action can process the request correctly:

<WebhookBody>

<name>Project</name>

<summary>Summary</summary>

</WebhookBody>

Status Code

200

 

Unsuccessful Responses

Scenario: You try to use a webhook that doesn't exist. or you omit the extension part of the URL.

URL

https://{tenant url}/api/rest/Webhooks/Execute?extension=NonExistentWebhook

OR

https://{tenant url}/api/rest/Webhooks/Execute

Method

POST
Header Name Authorization: REST API Key

Request Body
Key Value
Value Format Value
Body Text (JSON or XML)

{

“someData”:“someDataValue”,

“otherData”:“otherDataValue”

}

Status Code

400 Bad Request

Message

NON-EXISTENT WEBHOOK:

{

"ErrorCode": "UnhandledSystemException-",

"Message": "Unhandled system exception: Invalid Webhook Extension Provided. "

}

MISSING EXTENSION:

{

"ErrorCode": "UnhandledSystemException-",

"Message": "Unhandled system exception: Webhook validation failed for Execute operation. Errors: You must enter an endpoint extension to your base URL. "

}

Scenario: You are trying to use an incorrect or deactivated REST API key for authorization.

URL

https://{tenant url}/api/rest/Webhooks/Execute?extension=MyTestWebhook

Method

POST
Header Name Authorization: REST API Key (incorrect or deactivated)

Request Body
Key Value
Value Format Value
Body Text (JSON or XML)

{

“someData”:“someDataValue”,

“otherData”:“otherDataValue”

}

Status Code

401 Unauthorized

Message

{

"code": "ISM_4001",

"description": "Invalid Session key or Authentication token",

"message": "",

"help": ""

}

Scenario: You are trying to use a Request Body that is longer than 100,000 characters.

URL

https://{tenant url}/api/rest/Webhooks/Execute?extension=MyTestWebhook

Method

POST
Header Name Authorization: REST API Key

Request Body
Key Value
Value Format Value
Body Text (JSON or XML)

{

“someData”:“someDataValue”,

“otherData”:“otherDataValue”

}

Greater than 100,000 characters.

Status Code

400 Bad Request

Message

{

"ErrorCode": "UnhandledSystemException-",

"Message": "Unhandled system exception: Request Body must be less than or equal to 100,000 characters"

}

Scenario: You are trying to use a webhook extension that was incorrectly typed.

URL

https://{tenant url}/api/rest/Webhooks/Execute?extension=blahblahWebhook

Method

POST
Header Name Authorization: REST API Key

Request Body
Key Value
Value Format Value
Body Text (JSON or XML)

{

“someData”:“someDataValue”,

“otherData”:“otherDataValue”

}

Status Code

400 Bad Request

Message

{

"ErrorCode": "UnhandledSystemException-",

"Message": "Unhandled system exception: This webhook extension doesn't exist."

}