Webhooks reference

Cloud

Server v4+

Common top level keys of webhooks

Each webhook will have some common data as part of the event:

Field	Description	Type
`id`	ID used to uniquely identify each event from the system (the client can use this to deduplicate events)	String
`happened_at`	ISO 8601 timestamp representing when the event happened	String
`webhook`	A map of metadata representing the webhook that was triggered	Map

The event payloads are open maps, meaning new fields may be added to maps in the webhook payload without considering it a breaking change.

Common sub-entities of webhooks

The following sections describe the payloads of different events offered with CircleCI webhooks. The schema of these webhook events will often share data with other webhooks. These common maps of data are referred to as "sub-entities". For example, when you receive an event payload for the job-completed webhook, it will contain maps of data for your project, organization, job, workflow and pipeline.

Some common sub-entities that will appear across various webhooks are described in the following sections:

Project

The following data about the project associated with the webhook event is provided:

Field	Always present?	Description
id	yes	Unique ID of the project
slug	yes	String that can be used to refer to a specific project in many of CircleCI’s APIs (for example, `gh/circleci/web-ui`)
name	yes	Name of the project (for example, `web-ui`)

Organization

The following data about the organization associated with the webhook event is provided:

Field	Always present?	Description
id	yes	Unique ID of the organization
name	yes	Name of the organization (for example, `circleci`)

Job

A job typically represents one phase in a CircleCI workload (for example, "build", "test", or "deploy") and contains a series of steps.

The following data about the job associated with the webhook event is provided:

Field	Always present?	Description
`id`	yes	Unique ID of the job
`number`	yes	An auto-incrementing number for the job, sometimes used in CircleCI’s APIs to identify jobs within a project
`name`	yes	Name of the job as defined in .circleci/config.yml
`status`	yes	Current status of the job
`started_at`	yes	When the job started running
`stopped_at`	no	When the job reached a terminal state (if applicable)

Workflow

Workflows orchestrate jobs. The following data about the workflow associated with the webhook event is provided:

Field	Always present?	Description
`id`	Yes	Unique ID of the workflow
`name`	Yes	Name of the workflow as defined in .circleci/config.yml
`status`	No	Current status of the workflow. Not included in job-level webhooks
`created\_at`	Yes	When the workflow was created
`stopped_at`	No	When the workflow reached a terminal state (if applicable)
`url`	Yes	URL to the workflow in CircleCI’s UI

Pipeline

Pipelines are the most high-level unit of work, and contain zero or more workflows. A single git-push always triggers up to one pipeline. Pipelines can also be triggered manually through the API.

The following Data about the pipeline associated with the webhook event is provided:

Field	Always present?	Description
`id`	Yes	Globally unique ID of the pipeline
`number`	Yes	Number of the pipeline, which is auto-incrementing / unique per project
`created\_at`	Yes	When the pipeline was created
`trigger`	Yes	A map of metadata about what caused this pipeline to be created — see below
`trigger_parameters`	No	A map of metadata about the pipeline — see below
`vcs`	No	A map of metadata about the git commit associated with this pipeline — see below

Trigger

The following data about the trigger associated with the webhook event is provided:

Field	Always present?	Description
type	yes	How this pipeline was triggered (for example, "webhook", "api", "schedule")

Trigger parameters

Data associated to the pipeline. Present for pipelines associated with GitLab, GitHub App, or Bitbucket Data Center. For parameters available for GitHub OAuth app and Bitbucket Cloud integrations, see VCS below. To find out which GitHub integration you have, see the GitHub Apps integration page.

Field	Always present?	Description
`circleci`	yes	A map containing trigger information — see `circleci`
`git`	no	A map present when the pipeline is associated with a VCS provider
`gitlab`	no	A map present when the pipeline is associated with a GitLab, GitHub App or Bitbucket Data Center trigger

`circleci`

Field	Always present?	Description
`event_time`	yes	ISO 8601 timestamp representing when the pipeline was created
`event_type`	yes	Provider event type that triggered the pipeline (for example, `push`)
`trigger_type`	yes	Trigger provider (for example, `gitlab`)
`actor_id`	no	CircleCI user id that the pipeline was attributed to

VCS

The VCS map and its contents are always present for GitHub OAuth app and Bitbucket Cloud projects, but not for GitLab, GitHub App or Bitbucket Data Center projects. See trigger parameters above for GitLab, GitHub App or Bitbucket Data Center parameters. To find out which GitHub integration you have, see the GitHub Apps integration page.

Field	Always present?	Description
target_repository_url	no	URL to the repository building the commit
origin_repository_url	no	URL to the repository where the commit was made (this will only be different in the case of a forked pull request)
revision	no	Git commit being built
commit.subject	no	Commit subject (first line of the commit message). Note that long commit subjects may be truncated.
commit.body	no	Commit body (subsequent lines of the commit message). Note that long commit bodies may be truncated.
commit.author.name	no	Name of the author of this commit
commit.author.email	no	Email address of the author of this commit
commit.authored\_at	no	Timestamp of when the commit was authored
commit.committer.name	no	Name of the committer of this commit
commit.committer.email	no	Email address of the committer of this commit
commit.committed_at	no	Timestamp of when the commit was committed
branch	no	Branch being built
tag	no	Tag being built (mutually exclusive with "branch")

Sample webhook payloads

To find out which GitHub integration you have, see the GitHub Apps integration page.

`workflow-completed` for GitHub OAuth and Bitbucket Cloud

{
  "id": "3888f21b-eaa7-38e3-8f3d-75a63bba8895",
  "type": "workflow-completed",
  "happened_at": "2021-09-01T22:49:34.317Z",
  "webhook": {
    "id": "cf8c4fdd-0587-4da1-b4ca-4846e9640af9",
    "name": "Sample Webhook"
  },
  "project": {
    "id": "84996744-a854-4f5e-aea3-04e2851dc1d2",
    "name": "webhook-service",
    "slug": "github/circleci/webhook-service"
  },
  "organization": {
    "id": "f22b6566-597d-46d5-ba74-99ef5bb3d85c",
    "name": "circleci"
  },
  "workflow": {
    "id": "fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "name": "build-test-deploy",
    "created_at": "2021-09-01T22:49:03.616Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "url": "https://app.circleci.com/pipelines/github/circleci/webhook-service/130/workflows/fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "status": "success"
  },
  "pipeline": {
    "id": "1285fe1d-d3a6-44fc-8886-8979558254c4",
    "number": 130,
    "created_at": "2021-09-01T22:49:03.544Z",
    "trigger": {
      "type": "webhook"
    },
    "vcs": {
      "provider_name": "github",
      "origin_repository_url": "https://github.com/circleci/webhook-service",
      "target_repository_url": "https://github.com/circleci/webhook-service",
      "revision": "1dc6aa69429bff4806ad6afe58d3d8f57e25973e",
      "commit": {
        "subject": "Description of change",
        "body": "More details about the change",
        "author": {
          "name": "Author Name",
          "email": "author.email@example.com"
        },
        "authored_at": "2021-09-01T22:48:53Z",
        "committer": {
          "name": "Committer Name",
          "email": "committer.email@example.com"
        },
        "committed_at": "2021-09-01T22:48:53Z"
      },
      "branch": "main"
    }
  }
}

`job-completed` for GitHub OAuth and Bitbucket Cloud

{
  "id": "8bd71c28-4969-3677-8940-3e3a61c46660",
  "type": "job-completed",
  "happened_at": "2021-09-01T22:49:34.279Z",
  "webhook": {
    "id": "cf8c4fdd-0587-4da1-b4ca-4846e9640af9",
    "name": "Sample Webhook"
  },
  "project": {
    "id": "84996744-a854-4f5e-aea3-04e2851dc1d2",
    "name": "webhook-service",
    "slug": "github/circleci/webhook-service"
  },
  "organization": {
    "id": "f22b6566-597d-46d5-ba74-99ef5bb3d85c",
    "name": "circleci"
  },
  "pipeline": {
    "id": "1285fe1d-d3a6-44fc-8886-8979558254c4",
    "number": 130,
    "created_at": "2021-09-01T22:49:03.544Z",
    "trigger": {
      "type": "webhook"
    },
    "vcs": {
      "provider_name": "github",
      "origin_repository_url": "https://github.com/circleci/webhook-service",
      "target_repository_url": "https://github.com/circleci/webhook-service",
      "revision": "1dc6aa69429bff4806ad6afe58d3d8f57e25973e",
      "commit": {
        "subject": "Description of change",
        "body": "More details about the change",
        "author": {
          "name": "Author Name",
          "email": "author.email@example.com"
        },
        "authored_at": "2021-09-01T22:48:53Z",
        "committer": {
          "name": "Committer Name",
          "email": "committer.email@example.com"
        },
        "committed_at": "2021-09-01T22:48:53Z"
      },
      "branch": "main"
    }
  },
  "workflow": {
    "id": "fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "name": "welcome",
    "created_at": "2021-09-01T22:49:03.616Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "url": "https://app.circleci.com/pipelines/github/circleci/webhook-service/130/workflows/fda08377-fe7e-46b1-8992-3a7aaecac9c3"
  },
  "job": {
    "id": "8b91f9a8-7975-4e60-916c-f0152ccbc937",
    "name": "test",
    "started_at": "2021-09-01T22:49:28.841Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "status": "success",
    "number": 136
  }
}

`workflow-completed` for GitLab, GitHub App and Bitbucket Data Center

{
  "type": "workflow-completed",
  "id": "cbabbb40-6084-4f91-8311-a326c0f4963a",
  "happened_at": "2022-05-27T16:20:13.954328Z",
  "webhook": {
    "id": "e4da0d23-31cf-4047-8a7e-8ffb14cd0100",
    "name": "test"
  },
  "workflow": {
    "id": "c2006ece-778d-49fc-9e6e-b9965f72bee9",
    "name": "build",
    "created_at": "2022-05-27T16:20:07.631Z",
    "stopped_at": "2022-05-27T16:20:13.812Z",
    "url": "https://app.circleci.com/pipelines/circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt/1/workflows/c2006ece-778d-49fc-9e6e-b9965f72bee9",
    "status": "failed"
  },
  "pipeline": {
    "id": "37c74cb7-d64d-4032-8731-1cb95bfef921",
    "number": 1,
    "created_at": "2022-04-13T11:10:18.804Z",
    "trigger": {
      "type": "gitlab"
    },
    "trigger_parameters": {
      "gitlab": {
        "web_url": "https://gitlab.com/circleci/hello-world",
        "commit_author_name": "Commit Author",
        "user_id": "9534789",
        "user_name": "User name",
        "user_username": "username",
        "branch": "main",
        "commit_title": "Update README.md",
        "commit_message": "Update README.md",
        "total_commits_count": "1",
        "repo_url": "git@gitlab.com:circleci/hello-world.git",
        "user_avatar": "https://secure.gravatar.com/avatar",
        "type": "push",
        "project_id": "33852820",
        "ref": "refs/heads/main",
        "repo_name": "hello-world",
        "commit_author_email": "committer.email@example.com",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "commit_timestamp": "2022-04-13T11:10:16+00:00",
        "commit_sha": "850a1519f25d14e968649cc420d1bd381715c05c"
      },
      "git": {
        "tag": "",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "ref": "refs/heads/main",
        "branch": "main",
        "checkout_url": "git@gitlab.com:circleci/hello-world.git"
      },
      "circleci": {
        "event_time": "2022-04-13T11:10:18.349Z",
        "actor_id": "6a19122c-40e0-4d56-a875-aac6ccc27700",
        "event_type": "push",
        "trigger_type": "gitlab"
      }
    }
  },
  "project": {
    "id": "2a68fe5f-2fe5-4d4f-91e1-15f111116743",
    "name": "hello-world",
    "slug": "circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt"
  },
  "organization": {
    "id": "66491562-90a9-4065-9249-4b0ce3b77452",
    "name": "circleci"
  }
}

`job-completed` for GitLab, GitHub App and Bitbucket Data Center

{
  "type": "workflow-completed",
  "id": "47a497be-4498-4da0-a4e8-2dabd889af0f",
  "happened_at": "2022-05-27T16:20:13.954328Z",
  "webhook": {
    "id": "e4da0d23-31cf-4047-8a7e-8ffb14cd0100",
    "name": "test"
  },
  "job": {
    "id": "2fc6977d-7e45-4271-b355-0ea894d82017",
    "name": "say-hello",
    "started_at": "2022-07-11T12:16:37.435Z",
    "stopped_at": "2022-07-11T12:16:59.982Z",
    "status": "success",
    "number": 1
  }
  "pipeline": {
    "id": "37c74cb7-d64d-4032-8731-1cb95bfef921",
    "number": 1,
    "created_at": "2022-04-13T11:10:18.804Z",
    "trigger": {
      "type": "gitlab"
    },
    "trigger_parameters": {
      "gitlab": {
        "web_url": "https://gitlab.com/circleci/hello-world",
        "commit_author_name": "Commit Author",
        "user_id": "9534789",
        "user_name": "User name",
        "user_username": "username",
        "branch": "main",
        "commit_title": "Update README.md",
        "commit_message": "Update README.md",
        "total_commits_count": "1",
        "repo_url": "git@gitlab.com:circleci/hello-world.git",
        "user_avatar": "https://secure.gravatar.com/avatar",
        "type": "push",
        "project_id": "33852820",
        "ref": "refs/heads/main",
        "repo_name": "hello-world",
        "commit_author_email": "committer.email@example.com",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "commit_timestamp": "2022-04-13T11:10:16+00:00",
        "commit_sha": "850a1519f25d14e968649cc420d1bd381715c05c"
      },
      "git": {
        "tag": "",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "ref": "refs/heads/main",
        "branch": "main",
        "checkout_url": "git@gitlab.com:circleci/hello-world.git"
      },
      "circleci": {
        "event_time": "2022-04-13T11:10:18.349Z",
        "actor_id": "6a19122c-40e0-4d56-a875-aac6ccc27700",
        "event_type": "push",
        "trigger_type": "gitlab"
      }
    }
  },
  "project": {
    "id": "2a68fe5f-2fe5-4d4f-91e1-15f111116743",
    "name": "hello-world",
    "slug": "circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt"
  },
  "organization": {
    "id": "66491562-90a9-4065-9249-4b0ce3b77452",
    "name": "circleci"
  }
}