AWS::CodePipeline::Webhook
The AWS::CodePipeline::Webhook
resource creates and registers your
webhook. After the webhook is created and registered, it triggers your pipeline to start every
time an external event occurs. For more information, see Migrate polling pipelines to use event-based change detection in the AWS CodePipeline
User Guide.
We strongly recommend that you use AWS Secrets Manager to store your credentials. If you use Secrets Manager, you must have already configured and stored your secret parameters in Secrets Manager. For more information, see Using Dynamic References to Specify Template Values.
Important
When passing secret parameters, do not enter the value directly into the template. The value is rendered as plaintext and is therefore readable. For security reasons, do not use plaintext in your AWS CloudFormation template to store your credentials.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::CodePipeline::Webhook", "Properties" : { "Authentication" :
String
, "AuthenticationConfiguration" :WebhookAuthConfiguration
, "Filters" :[ WebhookFilterRule, ... ]
, "Name" :String
, "RegisterWithThirdParty" :Boolean
, "TargetAction" :String
, "TargetPipeline" :String
, "TargetPipelineVersion" :Integer
} }
YAML
Type: AWS::CodePipeline::Webhook Properties: Authentication:
String
AuthenticationConfiguration:WebhookAuthConfiguration
Filters:- WebhookFilterRule
Name:String
RegisterWithThirdParty:Boolean
TargetAction:String
TargetPipeline:String
TargetPipelineVersion:Integer
Properties
Authentication
-
Supported options are GITHUB_HMAC, IP, and UNAUTHENTICATED.
-
For information about the authentication scheme implemented by GITHUB_HMAC, see Securing your webhooks
on the GitHub Developer website. -
IP rejects webhooks trigger requests unless they originate from an IP address in the IP range whitelisted in the authentication configuration.
-
UNAUTHENTICATED accepts all webhook trigger requests regardless of origin.
Required: Yes
Type: String
Allowed values:
GITHUB_HMAC | IP | UNAUTHENTICATED
Update requires: No interruption
-
AuthenticationConfiguration
-
Properties that configure the authentication applied to incoming webhook trigger requests. The required properties depend on the authentication type. For GITHUB_HMAC, only the
SecretToken
property must be set. For IP, only theAllowedIPRange
property must be set to a valid CIDR range. For UNAUTHENTICATED, no properties can be set.Required: Yes
Type: WebhookAuthConfiguration
Update requires: No interruption
Filters
-
A list of rules applied to the body/payload sent in the POST request to a webhook URL. All defined rules must pass for the request to be accepted and the pipeline started.
Required: Yes
Type: List of WebhookFilterRule
Maximum:
5
Update requires: No interruption
Name
-
The name of the webhook.
Required: No
Type: String
Minimum:
1
Maximum:
100
Pattern:
[A-Za-z0-9.@\-_]+
Update requires: Replacement
RegisterWithThirdParty
-
Configures a connection between the webhook that was created and the external tool with events to be detected.
Required: No
Type: Boolean
Update requires: No interruption
TargetAction
-
The name of the action in a pipeline you want to connect to the webhook. The action must be from the source (first) stage of the pipeline.
Required: Yes
Type: String
Minimum:
1
Maximum:
100
Pattern:
[A-Za-z0-9.@\-_]+
Update requires: No interruption
TargetPipeline
-
The name of the pipeline you want to connect to the webhook.
Required: Yes
Type: String
Minimum:
1
Maximum:
100
Pattern:
[A-Za-z0-9.@\-_]+
Update requires: No interruption
TargetPipelineVersion
-
The version number of the pipeline to be connected to the trigger request.
Required: Yes
Type: Integer
Update requires: No interruption
Required: Yes
Type: Integer
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the webhook name, such as
MyFirstPipeline-SourceAction1-Webhook-utb9LrOl24Kk.
For more information about using the Ref
function, see Ref.
Fn::GetAtt
The Fn::GetAtt
intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.
For more information about using the Fn::GetAtt
intrinsic function, see Fn::GetAtt.
Examples
Webhook Resource Configuration
The following example creates a webhook named MyWebhook and registers the webhook for the pipeline's GitHub source repository. In this example, WebhookPipeline is the logical ID of the pipeline to which you want to add the webhook.
We strongly recommend that you use AWS Secrets Manager to store your credentials. If
you use Secrets Manager, you must have already configured and stored your secret
parameters in Secrets Manager. This example uses dynamic references to AWS Secrets Manager
for the GitHub credentials for your webhook, in the form of the
{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}
reference. For
more information, see Using Dynamic References to Specify Template Values.
Important
When passing secret parameters, do not enter the value directly into the template. The value is rendered as plaintext and is therefore readable. For security reasons, do not use plaintext in your AWS CloudFormation template to store your credentials.
JSON
{ "Webhook": { "Type": "AWS::CodePipeline::Webhook", "Properties": { "AuthenticationConfiguration": { "SecretToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}" }, "Filters": [ { "JsonPath": "$.ref", "MatchEquals": "refs/heads/{Branch}" } ], "Authentication": "GITHUB_HMAC", "TargetPipeline": { "Ref" : "WebhookPipeline" }, "TargetAction": "Source", "Name": "MyWebhook", "TargetPipelineVersion": { "Fn::GetAtt" : [ "WebhookPipeline", "Version" ] }, "RegisterWithThirdParty": "true" } } }
YAML
Webhook: Type: 'AWS::CodePipeline::Webhook' Properties: AuthenticationConfiguration: SecretToken: {{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} Filters: - JsonPath: "$.ref" MatchEquals: refs/heads/{Branch} Authentication: GITHUB_HMAC TargetPipeline: !Ref WebhookPipeline TargetAction: Source Name: MyWebhook TargetPipelineVersion: !GetAtt WebhookPipeline.Version RegisterWithThirdParty: 'true'