MSTeams Webhook Trigger

This plugin is based on generic webhook trigger plugin and HMAC decoding strategy is changed to meet ms teams criteria. Will work perfectly with teams outgoing webhook or if your service requires to first decode the HMAC Secret in BASE64 decoding.

This is a Jenkins plugin that can:

1. Receive any HTTP request, JENKINS_URL/teams-webhook-trigger/invoke
2. Authenticate Teams outgoing webhook HMAC
3. Extract values

• From POST content with JSONPath or XPath
• From the query parameters
• From the headers

3. Trigger a build with those values contribute as variables
4. Trigger several builds in one go with matching criteria

There is an optional feature to trigger jobs only if a supplied regular expression matches the extracted variables. Here is an example, let's say the post content looks like this:

{
  "before": "1848f1236ae15769e6b31e9c4477d8150b018453",
  "after": "5cab18338eaa83240ab86c7b775a9b27b51ef11d",
  "ref": "refs/heads/develop"
}

Then you can have a variable, resolved from post content, named ref of type JSONPath and with expression like $.ref . The optional filter text can be set to $ref and the filter regexp set to ^(refs/heads/develop|refs/heads/feature/.+)$ to trigger builds only for develop and feature-branches.

When using the plugin in several jobs, you will have the same URL trigger all jobs. If you want to trigger only a certain job you can:

• Use the token-parameter have different tokens for different jobs. Using only the token means only jobs with that exact token will be visible for that request. This will increase performance and reduce responses of each invocation.
• Or, add some request parameter (or header, or post content) and use the regexp filter to trigger only if that parameter has a specific value.

There is a special token parameter. When supplied, the invocation will only trigger jobs with that exact token. The token also allows invocations without any other authentication credentials.

The token can be supplied as a:

• Request parameter:

  curl -vs http://localhost:8080/jenkins/teams-webhook-trigger/invoke?token=abc123 2>&1

• Token header:

  curl -vs -H "token: abc123" http://localhost:8080/jenkins/teams-webhook-trigger/invoke 2>&1

  • It will also detect X-Gitlab-Token.

• Authorization header of type Bearer :

  curl -vs -H "Authorization: Bearer abc123" http://localhost:8080/jenkins/teams-webhook-trigger/invoke 2>&1

Jenkins will batch builds of a job if those builds have same parameters. If this plugin gets invoked by many webhooks at the same time it may trigger only one build and it will have many Generic Cause as causes. This has been reported in many issues #64 #116 #126 #162 #171.

You can solve this by making the one job parameterized. Resolve one of the parameters with something unique from the webhook. This will make each trigger unique and Jenkins will not batch the builds into one build.

The section on Default values explains the parameters.

Whitelist can be configured in Jenkins global configuration page. The whitelist will block any request to the plugin that is not configured in this list. The host can be empty to allow any, static IP, CIDR or ranges:

• 1.2.3.4
• 2.2.3.0/24
• 3.2.1.1-3.2.1.10
• 2001:0db8:85a3:0000:0000:8a2e:0370:7334
• 2002:0db8:85a3:0000:0000:8a2e:0370:7334/127
• 2001:0db8:85a3:0000:0000:8a2e:0370:7334-2001:0db8:85a3:0000:0000:8a2e:0370:7335

The hosts can optionally also be verified with HMAC.

If you are fiddling with expressions, you may want to checkout:

• This JSONPath site
• This XPath site
• This regexp site Also syntax here.

It's probably easiest to do with curl. Given that you have configured a Jenkins job to trigger on Generic Webhook, here are some examples of how to start the jobs.

curl -vs http://localhost:8080/jenkins/teams-webhook-trigger/invoke 2>&1

This should start your job, if the job has no token configured and no security enabled. If you have security enabled you may need to authenticate:

curl -vs http://theusername:thepasssword@localhost:8080/jenkins/teams-webhook-trigger/invoke 2>&1

If your job has a token you don't need to supply other credentials. You can specify the token like this:

curl -vs http://localhost:8080/jenkins/teams-webhook-trigger/invoke?token=TOKEN_HERE 2>&1

If you want to trigger with token and some post content, curl can dot that like this.

curl -v -H "Content-Type: application/json" -X POST -d '{ "app":{ "name":"some value" }}' http://localhost:8080/jenkins/teams-webhook-trigger/invoke?token=TOKEN_HERE

The plugin can be configured with default values. Like below:

But if you execute the job manually (or replay a pipeline), this default value will not be used. Because the plugin will not be invoked at all. You can solve this by checking the "This job is parameterized" and add a parameter with the same name as the one you configured in the plugin. Like this:

Now this default value will be used both when you trigger the job manually, replaying pipeline, and when you trigger it with the plugin!

This plugin can be used with the Job DSL Plugin.

Job DSL supports injecting credenials when processing the DSL. You can use that if you want the token to be set from credentials.

pipelineJob('Teams Webhook DSL Job Example') {
 parameters {
  stringParam('VARIABLE_FROM_POST', '')
 }

 triggers {
  teamsTrigger {
   genericVariables {
    genericVariable {
     key("VARIABLE_FROM_POST")
     value("\$.something")
     expressionType("JSONPath") //Optional, defaults to JSONPath
     regexpFilter("") //Optional, defaults to empty string
     defaultValue("") //Optional, defaults to empty string
    }
   }
   genericRequestVariables {
    genericRequestVariable {
     key("requestParameterName")
     regexpFilter("")
    }
   }
   genericHeaderVariables {
    genericHeaderVariable {
     key("requestHeaderName")
     regexpFilter("")
    }
   }
   token('abc123')
   tokenCredentialId('')
   printContributedVariables(true)
   printPostContent(true)
   silentResponse(false)
   regexpFilterText("\$VARIABLE_FROM_POST")
   regexpFilterExpression("aRegExp")
  }
 }

 definition {
  cps {
   // Or just refer to a Jenkinsfile containing the pipeline
   script('''
    node {
     stage('Some Stage') {
      println "VARIABLE_FROM_POST: " + VARIABLE_FROM_POST
     }
    }
   ''')
   sandbox()
  }
 }
}

When configuring from pipeline (not multibranch pipeline), that pipeline needs to run once, to apply the plugin trigger config, and after that this plugin will be able to trigger the job. This is how Jenkins works, not something implemented in this plugin.

You need to run it once to have the properties applied. You can verify that the properties has been applied by opening the configuration view (or view configuration if using multibranch pipeline) of the job. You will see that the "teams Webhook Trigger" is checked and will now have values from your pipeline.

You can avoid having to run twice, by using Job DSL and have Job DSL create pipeline jobs with the plugin configured in that DSL.

This plugin can be used in the jobs created by the Pipeline Multibranch Plugin. If you are looking for a way to trigger a scan in the Pipeline Multibranch Plugin you can use the Multibranch Scan Webhook Trigger Plugin.

You can use the credentials plugin to provide the token from credentials.

withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) {
 properties([
  pipelineTriggers([
   [$class: 'TeamsTrigger',
    ...
    token: credentialsVariable,
    ...
   ]
  ])
 ])
}

Perhaps you want a different token for each job.

 properties([
  pipelineTriggers([
   [$class: 'TeamsTrigger',
    ...
    token: env.JOB_NAME,
    ...
   ]
  ])
 ])

Or have a credentials string prefixed with the job name.

withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) {
 properties([
  pipelineTriggers([
   [$class: 'TeamsTrigger',
    ...
    token: env.JOB_NAME + credentialsVariable,
    ...
   ]
  ])
 ])
}

With a scripted Jenkinsfile like this:

node {
 properties([
  pipelineTriggers([
   [$class: 'TeamsTrigger',
    genericVariables: [
     [key: 'ref', value: '$.ref'],
     [
      key: 'before',
      value: '$.before',
      expressionType: 'JSONPath', //Optional, defaults to JSONPath
      regexpFilter: '', //Optional, defaults to empty string
      defaultValue: '' //Optional, defaults to empty string
     ]
    ],
    genericRequestVariables: [
     [key: 'requestWithNumber', regexpFilter: '[^0-9]'],
     [key: 'requestWithString', regexpFilter: '']
    ],
    genericHeaderVariables: [
     [key: 'headerWithNumber', regexpFilter: '[^0-9]'],
     [key: 'headerWithString', regexpFilter: '']
    ],

    causeString: 'Triggered on $ref',

    token: 'abc123',
    tokenCredentialId: '',

    printContributedVariables: true,
    printPostContent: true,

    silentResponse: false,

    regexpFilterText: '$ref',
    regexpFilterExpression: 'refs/heads/' + BRANCH_NAME
   ]
  ])
 ])

 stage("build") {
  sh '''
  echo Variables from shell:
  echo ref $ref
  echo before $before
  echo requestWithNumber $requestWithNumber
  echo requestWithString $requestWithString
  echo headerWithNumber $headerWithNumber
  echo headerWithString $headerWithString
  '''
 }
}

With a declarative Jenkinsfile like this:

pipeline {
  agent any
  triggers {
    TeamsTrigger(
     genericVariables: [
      [key: 'ref', value: '$.ref']
     ],

     causeString: 'Triggered on $ref',

     token: 'abc123',
     tokenCredentialId: '',

     printContributedVariables: true,
     printPostContent: true,

     silentResponse: false,

     regexpFilterText: '$ref',
     regexpFilterExpression: 'refs/heads/' + BRANCH_NAME
    )
  }
  stages {
    stage('Some step') {
      steps {
        sh "echo $ref"
      }
    }
  }
}

It can be triggered with something like:

curl -X POST -H "Content-Type: application/json" -H "headerWithNumber: nbr123" -H "headerWithString: a b c" -d '{ "before": "1848f12", "after": "5cab1", "ref": "refs/heads/develop" }' -vs http://admin:admin@localhost:8080/jenkins/teams-webhook-trigger/invoke?requestWithNumber=nbr%20123\&requestWithString=a%20string

And the job will have this in the log:

Contributing variables:

    headerWithString_0 = a b c
    requestWithNumber_0 = 123
    ref = refs/heads/develop
    headerWithNumber = 123
    requestWithNumber = 123
    before = 1848f12
    requestWithString_0 = a string
    headerWithNumber_0 = 123
    headerWithString = a b c
    requestWithString = a string

More details on Jenkins plugin development is available here.

A release is created like this. You need to clone from jenkinsci-repo, with https and have username/password in settings.xml.

mvn release:prepare release:perform