Adding a webhook

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. In the CSRF protection section, turn on the Use CSRF protection toggle switch to configure the CSRF parameters, which enhance security when the webhook communicates with a third-party application such as Jenkins. The CSRF fields are displayed.
4. Specify the relevant CSRF URL location. This is used to obtain Jenkins' CSRF crumb that will be added as a header in the callback URL. The CSRF URL must begin with http:// or https://.
5. Select the required CSRF 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:
   • DELETE—deletes a resource
   • GET—retrieves a resource
   • POST—creates a resource
   • PUT—modifies a resource
     For example, to create a new item in a third-party application when the response was received, select POST.
6. Define the CSRF Header 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.
7. In the SSL certificate support section, turn on the Use SSL protection toggle switch to associate an SSL certificate with the webhook. This option enhances security when the webhook communicates with a third-party application, such as Jenkins. The SSL certificate fields are displayed.
8. Select the required SSL certificate name. This list includes all the certificates uploaded in the Certificates page. For more information, see Managing-certificates.
9. Enter the SSL certificate password, which was used when uploading the certificate in the Certificates page.
10. In the Product Support section, 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.
11. 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.

12. 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 alphanumeric characters. You can specify up to 50 comma-separated values. Valid characters are alphabets from A to Z in upper or lower case, numbers from 0 to 9, and special characters such as #, $, and @.
      2. Specify the name of the Sub application of the Code Pipeline  resource. Each sub application name must not exceed eight alphanumeric characters. You can specify up to 50 comma-separated values. Valid characters are alphabets from A to Z in upper or lower case, numbers from 0 to 9, and special characters such as #, $, and @.
         If the Sub application field is left blank when creating or updating webhooks, the default value of Sub Application will be same as Application.
      3. Specify the current Level of the Code Pipeline resource. Each level must not exceed four alphanumeric characters. You can specify up to 25 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.

    To select all available values of a field, enter two asterisks in that field.

13. After configuring the webhook, click Save to submit the request to the selected mainframe product, if the webhook is enabled. If enabled, you must select an authentication method to establish connection to the mainframe product.
    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.