Skip to main content

Configure the CREATE payload body for an alert webhook

This is Step 3 in the procedure for creating a new outbound alert webhook.

The Payload Body for CREATE Operation section specifies the JSON payload that the webhook includes with each CREATE request it sends to the external system.

There are two ways to define payloads:

Note

Moogsoft Cloud payload fields are context-aware and can be replaced by text substitutions. Be sure to review Field and tag substitution for JSON payloads to better understand how predefined rules are used by the system.

Edit the payload using the Input Assistant

Toggle on the Input Assistant to add Key/Value pairs to the payload using a form interface.

To add an additional payload item, click ADD KEY/VALUE PAIR. Provide the Name and Value using the menu.

Note that field values in the JSON appear with a dollar sign ($) prepended to identify the value as a field substitution. 

Use the menu to experiment with inserting field values, such as location fields (for example, ${location.city}) or tags (for example, ${tags.collector}). 

The Input Assistant only supports simple JSON payload, with a single level of depth. To create nested payload items, you must toggle off the Input Assistant and edit the JSON directly.

Edit the JSON payload directly

Toggle off the Input Assistant to edit the payload using free typing.

The payload editor lets you can create a complex, multilevel, nested JSON object. However, after you create nested levels, you cannot re-enable the Input Assistant.

Type the dollar sign ($) while editing to open a menu listing the fields with available value substitutions. For example, the ticket ID parsed from the CREATE response will have the field name ${external_id}.

Click the JSON PREVIEW tab to see sample substitutions of the fields with representative values. The preview window shows what the payload looks like when Moogsoft sends it to the external system. Tag values are not substituted here because it might be confusing if the wrong data is shown, but the preview is helpful for matching braces, checking commas, and finding other structural problems. Note that the payload preview is not a JSON linter and does not perform validation. 

Tip

Use the JSON PREVIEW option often to see what the webhook payload will look like. Note that the webhook needs to have a name for the JSON PREVIEW to work.

Send Payload as List

Toggle on the Send Payload as List option to add square brackets [ ] to your payload and convert it to a list. Enable this setting if your target system requires payloads formatted as lists.

  • If the input value is already a list, the entire payload is sent as a list instead of as individual items.

  • If the input value is null (does not exist), then enabling this setting will create an empty list.

  • If the input value exists, then enabling this setting will convert the value into a list.

    Do not put quotation marks around the JSON variable in your payload body when using this setting. Only include quotation marks if you want the output to be a string of concatenated values, not a list.

Manage JSON variable type declarations

If your target system requires certain information in a specific data type, select the variable from the Variable list and choose the preferred data type from the Type list.

Send custom values

To send a specific value instead of the input value received from Moogsoft, click Custom Values and substitute a different value to send instead when the Input Value is received.

Substituting custom values lets you modify data in a way that makes it more relevant, understandable, or useful on the external system. For example, you could set a custom value for the $status value of "In Progress" to "In Process" to support alternative terminology, change raw information (such as codes for systems or locations) to more understandable names, identify similar information as the same by changing a variable value to be the same for several different values, or perform other useful substitutions.

Test the Payload Body

After creating the payload for the CREATE operation, you can perform an end-to-end validation by clicking Test. Test validates the end-to-end connectivity to the endpoint by executing an actual REST call on Create and Update. Testing can help you build your payload incrementally, ensuring both connectivity and payload validity at each step (by validating authorization, ticket ID extraction, and other payload components). Note that testing the payload creates a ticket, so be sure to close that ticket so that there are no dangling tickets left at the endpoint.

Tip

TEST is enabled only after you enter a Name and URL for the outbound webhook. Use the Test option frequently. It is a best practice to test after each change you make to the JSON to ensure the payload is still valid after each change. 

Testing performs variable value substitution on a best-effort basis and performs end-to-end validation.

Note that there are some fields that the payload test cannot actually substitute values for, such as tags. Because it has no knowledge of the actual values, it cannot determine reasonable values to substitute, and so does not add any text. If the external endpoint requires a tag field to have a value, manually add some text in the summary field just for the purpose of the test. Delete it when your test is complete.

TestOutput2.png