Adding a webhook

You can add a webhook to integrate products such as Code Pipeline and Abend-AID with third-party applications, so that the third-party application receives a notification when an action occurs in the BMC AMI mainframe product. Webhooks fetch such data from the Code Pipeline and Abend-AID mainframe products.

To add a webhook:

1. On the Webhooks page, click Add.

2. In the Add webhook dialog box, select either Webhook enabled or Webhook disabled to indicate if the current webhook must be active. If you select Webhook enabled, requests to the BMC AMI mainframe product will be sent and responses will also be received. If the webhook was previously enabled, disabling it tells the BMC AMI mainframe product to stop sending any future responses.

   Important

   To select Webhook enabled, you must establish a host connection to the mainframe product.

3. Enter a meaningful Name for the webhook.
4. Specify the URL location to which the BMC mainframe product responses should be sent. The URL must begin with http:// or https://. For information about the values that can be substituted in the variables, see Variable Substitution.
5. Select the required HTTP Request method to be used when the response from a BMC AMI mainframe product is forwarded to the specified URL. 
   If the third-party application follows common conventions, the method options perform the following actions:

1. • DELETE—deletes a resource

1. • GET—retrieves a resource

1. • POST—creates a resource

1. • PUT—modifies a resource
     For example, to create a new item in a third-party application when the response was received, select POST.
2. Define the HTTP request Headers that should be sent with the response to the third-party application by clicking Add header and entering a suitable Name and Value.
   For example, to provide authentication information to a third-party application, click Add header. In the Name field, enter Authorization. In the Value field, enter your credential information, such as Basic dXNlcjpwYXNzd29yZA==ik. You can configure more than one header. You can delete a header configured by clicking next to that header.
3. Select the required mainframe Product name to indicate which BMC AMI mainframe product should receive the request. Based on the selected product, the subsequent fields are dynamically displayed.
4. When you select the Abend-AID product, the Expire in days field is displayed. Specify the number of days after which you want the Abend-AID webhook to expire and be automatically deleted. You must specify a value from 0 to 365 days.

5. Based on the selected product, configure the Product event criteria pane:

   • For Code Pipeline, configure the following fields:
     1. Specify the name of the Application of a Code Pipeline resource. Each application name must not exceed eight characters. You may specify multiple comma-separated values.
     2. Specify the name of the Sub application of the Code Pipeline  resource. Each sub application name must not exceed eight characters. If the Sub Application field is left blank when creating or updating webhooks, the default value of Sub Application will be same as Application. You may specify multiple comma-separated values.
     3. Specify the current Level of the Code Pipeline resource. Each level must not exceed four characters. You may specify multiple comma-separated values.
     4. In Event name, specify the name of the event associated with the Code Pipeline resource. You may specify multiple comma-separated values.
     5. Select the required Operations for which you want responses. For example, to receive responses when a Deploy or Promote occurs, select Deploy and Promote.
   • For Abend-AID, configure the following fields:
     1. In Program names, enter the names of the abending program associated with an Abend-AID resource. You may specify multiple comma-separated values.
     2. Enter the User IDs of the abending jobs associated with an Abend-AID resource. You may specify multiple comma-separated values.
     3. Specify the Abend codes, which are the system or user abnormal termination codes, or "SNAP" for a SNAP-AID report, or the PL/I on-code associated with an Abend-AID resource. You may specify multiple comma-separated values.
     4. Enter the Job names of the abending jobs associated with an Abend-AID resource. You may specify multiple comma-separated values.
     5. In CICS or IMS Regions, enter the SYSID of the abending job associated with an Abend-AID resource. You may specify multiple comma-separated values.
     6. In Number of duplicates, specify the number of times the specified event criteria must match before triggering the webhook.

   Important

   You can mask the Event Criteria with asterisks in the fields. For example, Program name: PGM***

   If you enter a single asterisk (*) in the field, that field is ignored from the criteria list.

6. After configuring the webhook, click Save to submit the request to the selected mainframe product, if the webhook is enabled.
   The configured webhook appears in the list of webhooks.

Variable substitution

You can substitute variables in the URL, request headers, and request body fields. A string enclosed with $$ is replaced with an associated value. For example, if the mainframe product supplied an ID when a notification was sent, the ID could be dynamically added to the URL by placing a variable in the URL as follows:

http://sample.com/endpoint/$$ID$$

If the ID that was sent was 123-456-789, then the URL appears as follows:

http://sample.com/endpoint/123-456-789

Code Pipeline variables

The following variables are available for substituting values from Code Pipeline:

Abend-AID variables

The following variables are available for substituting values from Abend-AID:

Webhook example

As a company practicing DevOps, you are using BMC AMI Products for Web, BMC AMI DevX Code Pipeline, and Slack. You want a notification to be sent to Slack whenever a promote occurs in Code Pipeline. To achieve this, you must create a webhook in CES with the following configuration options:

• Webhook enabled: On
• Name: Code Pipeline  Promote Slack Notification
• URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
• Request method: POST
• Request headers: Content-type application/json
• Request body: { “text” : “A promote occurred in Code Pipeline” }
• Product: Code Pipeline
• Event Type: Promote

The “Event Criteria” was left empty so as not to filter the responses to a specific application, level, or event name. As a result, you will receive a message in Slack for all promotes that occur in Code Pipeline.

Webhook example with variable substitution

As a company practicing DevOps, you are using BMC AMI Products for Web, BMC AMI DevX Code Pipeline, and Slack. You want a notification to be sent to Slack whenever a promote occurs in Code Pipeline. To achieve this, you must create a webhook in CES with the following configuration options:

• Webhook enabled: On
• Name: Code Pipeline Promote Slack Notification
• URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
• Request method: POST
• Request headers: Content-type application/json
• Request body: {"text" : "A promote occurred in Code Pipeline for set: $$setID$$ at level: $$level$$ with a status of: $$eventNames$$"}
• Product: Code Pipeline
• Event Type: Promote

The URL will receive a POST request with the following JSON body:

{
"text" : "A promote occurred in Code Pipeline for set: S000000021 at level: DEV1 with a status of: success"
}

The “Event Criteria” was left empty so as not to filter the responses to a specific application, level, or event name. As a result, you will receive a message in Slack for all promotes that occur in Code Pipeline.