Jenkins Integration
Example to integrate Jenkins using Webhooks
Home / Keptn v1 Docs / Release 0.10.0 / Custom Integrations / Webhook Integration
Learn how to integrate external tooling using Webhooks
Example to integrate Jenkins using Webhooks
Example to integrate Slack using Webhooks
Keptn has a built-in capability to integrate your webhooks into the sequence orchestration of Keptn. This lets you call custom HTTP endpoints when running a delivery or remediation sequence that triggers a certain task. By using this integration, you can easily send the state of a task to a third-party tool or service. This allows you to integrate various tools such as testing services, existing CI/CD pipelines, and incident management services.
Webhooks are created at a Task level and can be triggered by the following event types:
Event types | Description |
---|---|
Task triggered | The task has been triggered but is not yet running. |
Task started | The task has begun running. |
Task finished | The task has finished. |
To create a webhook integration, open Keptn Bridge, select a project, and go to the Uniform page. Then select
webhook-service, and click the Add subscription
button.
In this form, provide the information for the task subscription and webhook configuration:
Subscription:
test
or deployment
)triggered
, started
, of finished
Webhook configuration:
GET
, POST
or PUT
.Click Create subscription to save and enable the webhook for your integration.
The output format of the webhook (i.e., the payload of the request body) can be customized using event data to match the
required input format of the tool you are integrating with. Therefore, you can reference the data field (event property)
using Go templating. For example, if you would like to get the value of the project
property from the
subscribed event, type in: {{.data.project}}
. A look at the example event can help to identify the proper data field.
An example of a customized request payload:
{
"text": "Evaluation in {{.data.stage}} finished with result {{.data.evaluation.result}} and score {{.data.evaluation.score}}."
}
Based on the Go templating capabilities, you can:
"{{if .fieldName}}{{.fieldName}}{{ else }}No field name set{{ end }}"
"{{ index .articles.Content 0 }}"
An example of a customized request payload using a condition on an array element:
{
"deploymentURL": "{{if index .data.deployment.deploymentURIsPublic 0}}{{index .data.deployment.deploymentURIsPublic 0}}{{else}}No deployment URL provided{{end}}"
}
For a more convenient way, a feature is planned where you can put your cursor in the text field at the spot where you would like to customize the payload. Then click the computer icon that opens a list of data fields you can add to the payload. This list of data fields is derived from the event your webhook is subscribed to.
When integrating tools by calling their endpoints, many times authentication is needed. This is done by storing an authentication token that is part of the webhook request. In Keptn, you do this as follows:
Create a secret with a unique name
, secret scope set to keptn-webhook-service
, and a key:value
pair whereas the key is a unique identifier of your secret and the value holds the sensitive data.
When configuring your webhook, you can reference the sensitive data as part of the URL, Custom header, and in the Custom payload. Therefore, click the key icon that opens the list of available secrets. Select your secret and specify the key that refers to the sensitive data you would like to include at this point.
The key-value pair will be automatically inserted into the selected field in the format {{.secret.name.key}}
.
When the webhook configuration is saved, the secret will be parsed into a different format, which looks like this: {{.env.secret_name_key}}
. This format represents a unique name that is a referrer to an entry in the envFrom
property in the webhook.yaml
file. This envFrom
property contains added secrets with a referrer name, the given secret name, and secret key.
apiVersion: webhookconfig.keptn.sh/v1alpha1
kind: WebhookConfig
metadata:
name: webhook-configuration
spec:
webhooks:
- type: sh.keptn.event.deployment.started
envFrom:
- name: secret_api_token
secretRef:
name: api
key: api-token
requests:
- "curl --request POST https://example.com?token={{.env.secret_api_token}}"
Prerequisite: This requires access to the upstream Git repo in order to modify the webhook configuration files.
For more advanced configuration options, you can modify the raw request declared as curl command. Therefore, you need to access the webhook.yaml
config file in the Git repo you set for an upstream. In this Git repo, you find the webhook.yaml
file based on the filters you selected on the task subscription, e.g., if a filter is set for stage production, go to the production branch.
Example of a webhook.yaml
containing a webhook request declared as curl command:
apiVersion: webhookconfig.keptn.sh/v1alpha1
kind: WebhookConfig
metadata:
name: webhook-configuration
spec:
webhooks:
- type: sh.keptn.event.evaluation.finished
requests:
- "curl --request POST --data '{\"text\":\"Evaluation {{.data.evaluation.result}} with a score of {{.data.evaluation.score}} \"}'
https://hooks.slack.com/services/{{.env.secretKey}}"
You can customize the curl depending on your needs.
Note: Adding a webhook by just extending this file is not supported, since the subscription to the event type is still missing.
If you subscribe your webhook to an event of type triggered
, Keptn automatically sends a started
event, executes
the webhook request via curl
, and automatically generates a finished
event.
In certain cases, you do want to have more control about this behaviour, e.g., to run a long-running test on Jenkins,
and let the receiving tool (in this case Jenkins) decide when to send the finished
event.
To achieve this, you need to edit your webhook configuration as follows:
finished
event by setting the flag sendFinished
to false
:apiVersion: webhookconfig.keptn.sh/v1alpha1
kind: WebhookConfig
metadata:
name: webhook-configuration
spec:
webhooks:
- type: sh.keptn.event.test.triggered
sendFinished: false
requests:
- "curl --request POST'
https://my.jenkins.127.0.0.1.nip.io/job/My-Job/buildWithParameters?token={{.env.jenkinsToken}}&triggeredid={{.id}}&shkeptncontext={{.shkeptncontext}}"
finished
event:
{{.id}}
- required in the triggeredid
attribute of the finished
event{{.shkeptncontext}}
- required in the shkeptncontext
attribute of the finished
event{{.data.project}}
, {{.data.service}}
, {{.data.stage}}
Note: Those fields can be either passed within the Data block, or as query params in the URL, depending on the receiving tools configuration.
finished
event is sent by Keptn, it is required to configure the receiving tool to send a finished
event to the /v1/event
endpoint of the Keptn API.To delete a webhook integration, click on the trash can icon next to the subscription. Note that deleting a webhook is permanent and cannot be reversed. Once deleted, Keptn will no longer send requests to the endpoint.
Note: Deleting a webhook means that the subscription in Uniform is deleted, as well as the webhook configuration file within the Git repo.