CodeBuild / Client / update_webhook

update_webhook

CodeBuild.Client.update_webhook(**kwargs)

Updates the webhook associated with an CodeBuild build project.

Note

If you use Bitbucket for your repository, rotateSecret is ignored.

See also: AWS API Documentation

Request Syntax

response = client.update_webhook(
    projectName='string',
    branchFilter='string',
    rotateSecret=True|False,
    filterGroups=[
        [
            {
                'type': 'EVENT'|'BASE_REF'|'HEAD_REF'|'ACTOR_ACCOUNT_ID'|'FILE_PATH'|'COMMIT_MESSAGE'|'WORKFLOW_NAME'|'TAG_NAME'|'RELEASE_NAME'|'REPOSITORY_NAME'|'ORGANIZATION_NAME',
                'pattern': 'string',
                'excludeMatchedPattern': True|False
            },
        ],
    ],
    buildType='BUILD'|'BUILD_BATCH'|'RUNNER_BUILDKITE_BUILD',
    pullRequestBuildPolicy={
        'requiresCommentApproval': 'DISABLED'|'ALL_PULL_REQUESTS'|'FORK_PULL_REQUESTS',
        'approverRoles': [
            'GITHUB_READ'|'GITHUB_TRIAGE'|'GITHUB_WRITE'|'GITHUB_MAINTAIN'|'GITHUB_ADMIN'|'GITLAB_GUEST'|'GITLAB_PLANNER'|'GITLAB_REPORTER'|'GITLAB_DEVELOPER'|'GITLAB_MAINTAINER'|'GITLAB_OWNER'|'BITBUCKET_READ'|'BITBUCKET_WRITE'|'BITBUCKET_ADMIN',
        ]
    }
)
Parameters:

  • projectName (string) –

    [REQUIRED]

    The name of the CodeBuild project.

  • branchFilter (string) –

    A regular expression used to determine which repository branches are built when a webhook is triggered. If the name of a branch matches the regular expression, then it is built. If branchFilter is empty, then all branches are built.

    Note

    It is recommended that you use filterGroups instead of branchFilter.

  • rotateSecret (boolean) – A boolean value that specifies whether the associated GitHub repository’s secret token should be updated. If you use Bitbucket for your repository, rotateSecret is ignored.

  • filterGroups (list) –

    An array of arrays of WebhookFilter objects used to determine if a webhook event can trigger a build. A filter group must contain at least one EVENT WebhookFilter.

    • (list) –

      • (dict) –

        A filter used to determine which webhooks trigger a build.

        • type (string) – [REQUIRED]

          The type of webhook filter. There are 11 webhook filter types: EVENT, ACTOR_ACCOUNT_ID, HEAD_REF, BASE_REF, FILE_PATH, COMMIT_MESSAGE, TAG_NAME, RELEASE_NAME, REPOSITORY_NAME, ORGANIZATION_NAME, and WORKFLOW_NAME.

          • EVENT

            • A webhook event triggers a build when the provided pattern matches one of nine event types: PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_CLOSED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, RELEASED, PRERELEASED, and WORKFLOW_JOB_QUEUED. The EVENT patterns are specified as a comma-separated string. For example, PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED filters all push, pull request created, and pull request updated events.

            Note

            Types PULL_REQUEST_REOPENED and WORKFLOW_JOB_QUEUED work with GitHub and GitHub Enterprise only. Types RELEASED and PRERELEASED work with GitHub only.

          • ACTOR_ACCOUNT_ID

            • A webhook event triggers a build when a GitHub, GitHub Enterprise, or Bitbucket account ID matches the regular expression pattern.

          • HEAD_REF

            • A webhook event triggers a build when the head reference matches the regular expression pattern. For example, refs/heads/branch-name and refs/tags/tag-name.

            Note

            Works with GitHub and GitHub Enterprise push, GitHub and GitHub Enterprise pull request, Bitbucket push, and Bitbucket pull request events.

          • BASE_REF

            • A webhook event triggers a build when the base reference matches the regular expression pattern. For example, refs/heads/branch-name.

            Note

            Works with pull request events only.

          • FILE_PATH

            • A webhook triggers a build when the path of a changed file matches the regular expression pattern.

            Note

            Works with push and pull request events only.

          • COMMIT_MESSAGE

            • A webhook triggers a build when the head commit message matches the regular expression pattern.

            Note

            Works with push and pull request events only.

          • TAG_NAME

            • A webhook triggers a build when the tag name of the release matches the regular expression pattern.

            Note

            Works with RELEASED and PRERELEASED events only.

          • RELEASE_NAME

            • A webhook triggers a build when the release name matches the regular expression pattern.

            Note

            Works with RELEASED and PRERELEASED events only.

          • REPOSITORY_NAME

            • A webhook triggers a build when the repository name matches the regular expression pattern.

            Note

            Works with GitHub global or organization webhooks only.

          • ORGANIZATION_NAME

            • A webhook triggers a build when the organization name matches the regular expression pattern.

            Note

            Works with GitHub global webhooks only.

          • WORKFLOW_NAME

            • A webhook triggers a build when the workflow name matches the regular expression pattern.

            Note

            Works with WORKFLOW_JOB_QUEUED events only.

            Note

            For CodeBuild-hosted Buildkite runner builds, WORKFLOW_NAME filters will filter by pipeline name.

        • pattern (string) – [REQUIRED]

          For a WebHookFilter that uses EVENT type, a comma-separated string that specifies one or more events. For example, the webhook filter PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED allows all push, pull request created, and pull request updated events to trigger a build.

          For a WebHookFilter that uses any of the other filter types, a regular expression pattern. For example, a WebHookFilter that uses HEAD_REF for its type and the pattern ^refs/heads/ triggers a build when the head reference is a branch with a reference name refs/heads/branch-name.

        • excludeMatchedPattern (boolean) –

          Used to indicate that the pattern determines which webhook events do not trigger a build. If true, then a webhook event that does not match the pattern triggers a build. If false, then a webhook event that matches the pattern triggers a build.

  • buildType (string) –

    Specifies the type of build this webhook will trigger.

    Note

    RUNNER_BUILDKITE_BUILD is only available for NO_SOURCE source type projects configured for Buildkite runner builds. For more information about CodeBuild-hosted Buildkite runner builds, see Tutorial: Configure a CodeBuild-hosted Buildkite runner in the CodeBuild user guide.

  • pullRequestBuildPolicy (dict) –

    A PullRequestBuildPolicy object that defines comment-based approval requirements for triggering builds on pull requests. This policy helps control when automated builds are executed based on contributor permissions and approval workflows.

    • requiresCommentApproval (string) – [REQUIRED]

      Specifies when comment-based approval is required before triggering a build on pull requests. This setting determines whether builds run automatically or require explicit approval through comments.

      • DISABLED: Builds trigger automatically without requiring comment approval

      • ALL_PULL_REQUESTS: All pull requests require comment approval before builds execute (unless contributor is one of the approver roles)

      • FORK_PULL_REQUESTS: Only pull requests from forked repositories require comment approval (unless contributor is one of the approver roles)

    • approverRoles (list) –

      List of repository roles that have approval privileges for pull request builds when comment approval is required. Only users with these roles can provide valid comment approvals. If a pull request contributor is one of these roles, their pull request builds will trigger automatically. This field is only applicable when requiresCommentApproval is not DISABLED.

      • (string) –

Return type:

dict

Returns:

Response Syntax

{
    'webhook': {
        'url': 'string',
        'payloadUrl': 'string',
        'secret': 'string',
        'branchFilter': 'string',
        'filterGroups': [
            [
                {
                    'type': 'EVENT'|'BASE_REF'|'HEAD_REF'|'ACTOR_ACCOUNT_ID'|'FILE_PATH'|'COMMIT_MESSAGE'|'WORKFLOW_NAME'|'TAG_NAME'|'RELEASE_NAME'|'REPOSITORY_NAME'|'ORGANIZATION_NAME',
                    'pattern': 'string',
                    'excludeMatchedPattern': True|False
                },
            ],
        ],
        'buildType': 'BUILD'|'BUILD_BATCH'|'RUNNER_BUILDKITE_BUILD',
        'manualCreation': True|False,
        'lastModifiedSecret': datetime(2015, 1, 1),
        'scopeConfiguration': {
            'name': 'string',
            'domain': 'string',
            'scope': 'GITHUB_ORGANIZATION'|'GITHUB_GLOBAL'|'GITLAB_GROUP'
        },
        'status': 'CREATING'|'CREATE_FAILED'|'ACTIVE'|'DELETING',
        'statusMessage': 'string',
        'pullRequestBuildPolicy': {
            'requiresCommentApproval': 'DISABLED'|'ALL_PULL_REQUESTS'|'FORK_PULL_REQUESTS',
            'approverRoles': [
                'GITHUB_READ'|'GITHUB_TRIAGE'|'GITHUB_WRITE'|'GITHUB_MAINTAIN'|'GITHUB_ADMIN'|'GITLAB_GUEST'|'GITLAB_PLANNER'|'GITLAB_REPORTER'|'GITLAB_DEVELOPER'|'GITLAB_MAINTAINER'|'GITLAB_OWNER'|'BITBUCKET_READ'|'BITBUCKET_WRITE'|'BITBUCKET_ADMIN',
            ]
        }
    }
}

Response Structure

  • (dict) –

    • webhook (dict) –

      Information about a repository’s webhook that is associated with a project in CodeBuild.

      • url (string) –

        The URL to the webhook.

      • payloadUrl (string) –

        The CodeBuild endpoint where webhook events are sent.

      • secret (string) –

        The secret token of the associated repository.

        Note

        A Bitbucket webhook does not support secret.

      • branchFilter (string) –

        A regular expression used to determine which repository branches are built when a webhook is triggered. If the name of a branch matches the regular expression, then it is built. If branchFilter is empty, then all branches are built.

        Note

        It is recommended that you use filterGroups instead of branchFilter.

      • filterGroups (list) –

        An array of arrays of WebhookFilter objects used to determine which webhooks are triggered. At least one WebhookFilter in the array must specify EVENT as its type.

        For a build to be triggered, at least one filter group in the filterGroups array must pass. For a filter group to pass, each of its filters must pass.

        • (list) –

          • (dict) –

            A filter used to determine which webhooks trigger a build.

            • type (string) –

              The type of webhook filter. There are 11 webhook filter types: EVENT, ACTOR_ACCOUNT_ID, HEAD_REF, BASE_REF, FILE_PATH, COMMIT_MESSAGE, TAG_NAME, RELEASE_NAME, REPOSITORY_NAME, ORGANIZATION_NAME, and WORKFLOW_NAME.

              • EVENT

                • A webhook event triggers a build when the provided pattern matches one of nine event types: PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_CLOSED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, RELEASED, PRERELEASED, and WORKFLOW_JOB_QUEUED. The EVENT patterns are specified as a comma-separated string. For example, PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED filters all push, pull request created, and pull request updated events.

                Note

                Types PULL_REQUEST_REOPENED and WORKFLOW_JOB_QUEUED work with GitHub and GitHub Enterprise only. Types RELEASED and PRERELEASED work with GitHub only.

              • ACTOR_ACCOUNT_ID

                • A webhook event triggers a build when a GitHub, GitHub Enterprise, or Bitbucket account ID matches the regular expression pattern.

              • HEAD_REF

                • A webhook event triggers a build when the head reference matches the regular expression pattern. For example, refs/heads/branch-name and refs/tags/tag-name.

                Note

                Works with GitHub and GitHub Enterprise push, GitHub and GitHub Enterprise pull request, Bitbucket push, and Bitbucket pull request events.

              • BASE_REF

                • A webhook event triggers a build when the base reference matches the regular expression pattern. For example, refs/heads/branch-name.

                Note

                Works with pull request events only.

              • FILE_PATH

                • A webhook triggers a build when the path of a changed file matches the regular expression pattern.

                Note

                Works with push and pull request events only.

              • COMMIT_MESSAGE

                • A webhook triggers a build when the head commit message matches the regular expression pattern.

                Note

                Works with push and pull request events only.

              • TAG_NAME

                • A webhook triggers a build when the tag name of the release matches the regular expression pattern.

                Note

                Works with RELEASED and PRERELEASED events only.

              • RELEASE_NAME

                • A webhook triggers a build when the release name matches the regular expression pattern.

                Note

                Works with RELEASED and PRERELEASED events only.

              • REPOSITORY_NAME

                • A webhook triggers a build when the repository name matches the regular expression pattern.

                Note

                Works with GitHub global or organization webhooks only.

              • ORGANIZATION_NAME

                • A webhook triggers a build when the organization name matches the regular expression pattern.

                Note

                Works with GitHub global webhooks only.

              • WORKFLOW_NAME

                • A webhook triggers a build when the workflow name matches the regular expression pattern.

                Note

                Works with WORKFLOW_JOB_QUEUED events only.

                Note

                For CodeBuild-hosted Buildkite runner builds, WORKFLOW_NAME filters will filter by pipeline name.

            • pattern (string) –

              For a WebHookFilter that uses EVENT type, a comma-separated string that specifies one or more events. For example, the webhook filter PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED allows all push, pull request created, and pull request updated events to trigger a build.

              For a WebHookFilter that uses any of the other filter types, a regular expression pattern. For example, a WebHookFilter that uses HEAD_REF for its type and the pattern ^refs/heads/ triggers a build when the head reference is a branch with a reference name refs/heads/branch-name.

            • excludeMatchedPattern (boolean) –

              Used to indicate that the pattern determines which webhook events do not trigger a build. If true, then a webhook event that does not match the pattern triggers a build. If false, then a webhook event that matches the pattern triggers a build.

      • buildType (string) –

        Specifies the type of build this webhook will trigger.

        Note

        RUNNER_BUILDKITE_BUILD is only available for NO_SOURCE source type projects configured for Buildkite runner builds. For more information about CodeBuild-hosted Buildkite runner builds, see Tutorial: Configure a CodeBuild-hosted Buildkite runner in the CodeBuild user guide.

      • manualCreation (boolean) –

        If manualCreation is true, CodeBuild doesn’t create a webhook in GitHub and instead returns payloadUrl and secret values for the webhook. The payloadUrl and secret values in the output can be used to manually create a webhook within GitHub.

        Note

        manualCreation is only available for GitHub webhooks.

      • lastModifiedSecret (datetime) –

        A timestamp that indicates the last time a repository’s secret token was modified.

      • scopeConfiguration (dict) –

        The scope configuration for global or organization webhooks.

        Note

        Global or organization webhooks are only available for GitHub and Github Enterprise webhooks.

        • name (string) –

          The name of either the group, enterprise, or organization that will send webhook events to CodeBuild, depending on the type of webhook.

        • domain (string) –

          The domain of the GitHub Enterprise organization or the GitLab Self Managed group. Note that this parameter is only required if your project’s source type is GITHUB_ENTERPRISE or GITLAB_SELF_MANAGED.

        • scope (string) –

          The type of scope for a GitHub or GitLab webhook. The scope default is GITHUB_ORGANIZATION.

      • status (string) –

        The status of the webhook. Valid values include:

        • CREATING: The webhook is being created.

        • CREATE_FAILED: The webhook has failed to create.

        • ACTIVE: The webhook has succeeded and is active.

        • DELETING: The webhook is being deleted.

      • statusMessage (string) –

        A message associated with the status of a webhook.

      • pullRequestBuildPolicy (dict) –

        A PullRequestBuildPolicy object that defines comment-based approval requirements for triggering builds on pull requests. This policy helps control when automated builds are executed based on contributor permissions and approval workflows.

        • requiresCommentApproval (string) –

          Specifies when comment-based approval is required before triggering a build on pull requests. This setting determines whether builds run automatically or require explicit approval through comments.

          • DISABLED: Builds trigger automatically without requiring comment approval

          • ALL_PULL_REQUESTS: All pull requests require comment approval before builds execute (unless contributor is one of the approver roles)

          • FORK_PULL_REQUESTS: Only pull requests from forked repositories require comment approval (unless contributor is one of the approver roles)

        • approverRoles (list) –

          List of repository roles that have approval privileges for pull request builds when comment approval is required. Only users with these roles can provide valid comment approvals. If a pull request contributor is one of these roles, their pull request builds will trigger automatically. This field is only applicable when requiresCommentApproval is not DISABLED.

          • (string) –

Exceptions