A webhook allows you to connect a platform you manage (either an API you create yourself, or a third party service) to a stream of future events.
Setting up a Webhook on CircleCI enables you to receive information (referred to as events) from CircleCI, as they happen. This can help you avoid polling the API or manually checking the CircleCI web application for desired information.
The rest of this document will detail how to set up a webhook as well as the shape of events that will be sent to your webhook destination.
Note: The Webhooks feature on CircleCI is currently in preview; documentation and features may change or be added to.
Webhooks can be leveraged for various purposes. Some possible examples might include:
- Building a custom dashboard to visualize or analyze workflow/job events.
- Sending data to incident management tools (such as Pagerduty).
- Use tools like Airtable to capture data and visualize it.
- Send events to communication apps, such as Slack.
- Use webhooks to be alerted when a workflow is cancelled, then use the API to rerun the workflow.
- Trigger internal notification systems to alert people when workflows/jobs complete.
- Build your own automation plugins and tools.
Setting up a hook
Webhooks are set up on a per-project basis. To get started:
- Visit a specific project you have setup on CircleCI.
- Click on Project Settings.
- In the sidebar of your Project Settings, click on Webhooks.
- Click Add Webhook.
- Fill out the Webhook form (the table below describes the fields and their intent):
- Provided your receiving API or third party service is set up, click Test Ping Event to dispatch a test event.
|Webhook name||Y||The name of your webhook|
|URL||Y||The URL the webhook will make POST requests to.|
|Certificate Validation||Y||Ensure the receiving host has a valid SSL certificate before sending an event 1.|
|Secret token||Y||Used by your API/platform to validate incoming data is from CircleCI.|
|Select an event||Y||You must select at least one event that will trigger a webhook.|
1Only leave this unchecked for testing purposes.
CircleCI currently offers webhooks for the following events:
|Event type||Description||Potential statuses||Included sub-entities|
|workflow-completed||A workflow has reached a terminal state||“success”, “failed”, “error”, “canceled”, “unauthorized”||project, organization, workflow, pipeline|
|job-completed||A job has reached a terminal state||“success”, “failed”, “canceled”, “unauthorized”||project, organization, workflow, pipeline, job|
Common top level keys
Each Webhook will have some common data as part of the event:
|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|
Note: The event payloads are open maps, meaning new fields may be added to maps in the webhook payload without considering it a breaking change.
The next sections describe the payloads of different events offered with
CircleCI webhooks. The schema of these webhook events will share often share
data with other webhooks - we refer to these as common maps of data as
“sub-entities”. For example, when you receive an event payload for the
job-completed webhook, it will contains maps of data for your project,
organization, job, workflow and pipeline.
Let’s look at some of the common sub-entities that will appear across various webhooks:
Data about the project associated with the webhook event.
|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 (e.g. “gh/circleci/web-ui”)|
|name||yes||Name of the project (e.g. “web-ui”)|
Data about the organization associated with the webhook event.
|id||yes||Unique ID of the organization|
|name||yes||Name of the organization (e.g. “circleci”)|
A job typically represents one phase in a CircleCI workload (e.g. “build”, “test”, or “deploy”) and contains a series of steps.
|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|
Workflows contain many jobs, which can run in parallel and/or have dependencies between them. A single git-push can trigger zero or more workflows, depending on the CircleCI configuration (but typically one will be triggered).
|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|
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.
|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|
|vcs||No||A map of metadata about the git commit associated with this pipeline – see below|
|type||yes||How this pipeline was triggered (e.g. “webhook”, “api”, “schedule”)|
|actor.id||No||The user who triggered the pipeline, if there is one|
Note: The vcs map or its contents may not always be provided in cases where the information doesn’t apply, such as future scenarios in which a pipeline isn’t associated with a git commit.
|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)|
|commit.body||no||Commit body (subsequent lines of the commit message)|
|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”)|
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.