Webhooks reference
On This Page
- Common top level keys of webhooks
- Common sub-entities of webhooks
- Project
- Organization
- Job
- Workflow
- Pipeline
- Trigger
- Trigger parameters
- circleci
- VCS
- Sample webhook payloads
- workflow-completed for GitHub and Bitbucket
- job-completed for GitHub and Bitbucket
- workflow-completed for Gitlab
- job-completed for Gitlab
- Next steps
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 dedupe 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, |
name | yes | Name of the project (for example, |
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 (e.g. "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 providers other than GitHub or Bitbucket. See VCS below for GitHub and Bitbucket.
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 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, |
trigger_type | yes | Trigger provider (for example, |
actor_id | no | CircleCI user id that the pipeline was attributed to |
VCS
The VCS map or its contents may not always be provided. Present for pipelines associated with GitHub and Bitbucket. See trigger parameters above for other providers. |
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
workflow-completed for GitHub and Bitbucket
{
"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 and Bitbucket
{
"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
{
"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
{
"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"
}
}
Next steps
-
Follow the Using webhooks with third party tools tutorial.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.