CodeBuild / Client / create_webhook

create_webhook#

CodeBuild.Client.create_webhook(**kwargs)#

For an existing CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, enables CodeBuild to start rebuilding the source code every time a code change is pushed to the repository.

Warning

If you enable webhooks for an CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit. One build is triggered through webhooks, and one through CodePipeline. Because billing is on a per-build basis, you are billed for both builds. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild. In the CodeBuild console, clear the Webhook box. For more information, see step 5 in Change a Build Project’s Settings.

See also: AWS API Documentation

Request Syntax

response = client.create_webhook(
    projectName='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',
                'pattern': 'string',
                'excludeMatchedPattern': True|False
            },
        ],
    ],
    buildType='BUILD'|'BUILD_BATCH',
    manualCreation=True|False,
    scopeConfiguration={
        'name': 'string',
        'domain': 'string',
        'scope': 'GITHUB_ORGANIZATION'|'GITHUB_GLOBAL'|'GITLAB_GROUP'
    }
)
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.

  • 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) – [REQUIRED]

          The type of webhook filter. There are nine webhook filter types: EVENT, ACTOR_ACCOUNT_ID, HEAD_REF, BASE_REF, FILE_PATH, COMMIT_MESSAGE, TAG_NAME, RELEASE_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 GitHub and Bitbucket events push and pull requests events. Also works with GitHub Enterprise push events, but does not work with GitHub Enterprise pull request events.

          • COMMIT_MESSAGE

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

            Note

            Works with GitHub and Bitbucket events push and pull requests events. Also works with GitHub Enterprise push events, but does not work with GitHub Enterprise pull request events.

          • 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.

          • WORKFLOW_NAME

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

            Note

            Works with WORKFLOW_JOB_QUEUED events only.

        • 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.

  • 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.

  • 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) – [REQUIRED]

      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) – [REQUIRED]

      The type of scope for a GitHub or GitLab webhook.

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',
                    'pattern': 'string',
                    'excludeMatchedPattern': True|False
                },
            ],
        ],
        'buildType': 'BUILD'|'BUILD_BATCH',
        'manualCreation': True|False,
        'lastModifiedSecret': datetime(2015, 1, 1),
        'scopeConfiguration': {
            'name': 'string',
            'domain': 'string',
            'scope': 'GITHUB_ORGANIZATION'|'GITHUB_GLOBAL'|'GITLAB_GROUP'
        }
    }
}

Response Structure

  • (dict) –

    • webhook (dict) –

      Information about a webhook that connects repository events to a build 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 nine webhook filter types: EVENT, ACTOR_ACCOUNT_ID, HEAD_REF, BASE_REF, FILE_PATH, COMMIT_MESSAGE, TAG_NAME, RELEASE_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 GitHub and Bitbucket events push and pull requests events. Also works with GitHub Enterprise push events, but does not work with GitHub Enterprise pull request events.

              • COMMIT_MESSAGE

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

                Note

                Works with GitHub and Bitbucket events push and pull requests events. Also works with GitHub Enterprise push events, but does not work with GitHub Enterprise pull request events.

              • 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.

              • WORKFLOW_NAME

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

                Note

                Works with WORKFLOW_JOB_QUEUED events only.

            • 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.

      • 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.

Exceptions

  • CodeBuild.Client.exceptions.InvalidInputException

  • CodeBuild.Client.exceptions.OAuthProviderException

  • CodeBuild.Client.exceptions.ResourceAlreadyExistsException

  • CodeBuild.Client.exceptions.ResourceNotFoundException