Docs
circleci.com
Start Building for Free

Webhooks

1 week ago8 min read
Cloud
Server v4.x
Server v3.x
On This Page

Webhooks overview

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 document details how to set up a webhook, as well as the shape of events that will be sent to your webhook destination.

Use cases for webhooks

Webhooks can be leveraged for various purposes. Some possible use cases for webhooks might include:

  • Building a custom dashboard to visualize or analyze workflow/job events
  • Sending data to incident management tools (such as PagerDuty)
  • Using tools like Airtable to capture data and visualize it
  • Alerting when a workflow is cancelled, then using the API to rerun the workflow
  • Triggering internal notification systems to alert people when workflows/jobs complete
  • Building your own automation plugins and tools

Communication protocol with webhooks

A webhook is sent whenever an event occurs on the CircleCI platform.

A webhook is sent using an HTTP POST to the URL that was registered when the webhook was created, with a body encoded using JSON.

CircleCI expects that the server that responds to a webhook will return a 2xx response code. If a non-2xx response is received, CircleCI will retry at a later time. If CircleCI does not receive a response to the webhook within a short period of time, CircleCI will assume that delivery has failed, and will retry at a later time. The timeout period is currently 5 seconds, but is subject to change during the preview period. The exact details of the retry policy are not currently documented, and are subject to change during the preview period.

Webhook requests may be duplicated. To deduplicate (prevent requests from being duplicated for a specific event), there is an id property in the webhook payload that can be used to identify the event for this purpose.

If you have feedback about timeouts and retries, please get get in touch with our team.

Webhook headers

A number of HTTP headers are set on webhooks, as detailed in the table below.

Header NameValue
Content-Typeapplication/json
User-AgentA string indicating that the sender was CircleCI (CircleCI-Webhook/1.0). The value is subject to change during the preview period.
Circleci-Event-TypeThe type of event, (workflow-completed, job-completed, etc)
Circleci-SignatureWhen present, this signature can be used to verify that the sender of the webhook has access to the secret token.

Setting up a webhook

Webhooks are set up on a per-project basis, either within the CircleCI app or via API.

To configure webhooks via API see our documentation for Webhooks Public API.

To configure webhooks within the CircleCI app:

  1. Visit a specific project you have set up on CircleCI
  2. Click on Project Settings
  3. In the sidebar of your Project Settings, click on Webhooks
  4. Click Add Webhook
  5. Fill out the webhook form (the table below describes the fields and their intent)
  6. Provided your receiving API or third party service is set up, click Test Ping Event to dispatch a test event. Note that the test ping event has an abbreviated payload for ease of testing. See full examples of workflow-completed and job-completed events below.
FieldRequired?Intent
Webhook nameYThe name of your webhook
URLYThe URL the webhook will make POST requests to
Certificate ValidationYEnsure the receiving host has a valid SSL certificate before sending an event 1
Secret tokenYUsed by your API/platform to validate incoming data is from CircleCI
Select an eventYYou must select at least one event that will trigger a webhook

1Only leave this unchecked for testing purposes.

Webhook payload signature

You should validate incoming webhooks to verify that they are coming from CircleCI. To support this, when creating a webhook, you can optionally provide a secret token. Each outgoing HTTP request to your service will contain a circleci-signature header. This header will consist of a comma-separated list of versioned signatures.

POST /uri HTTP/1.1
Host: your-webhook-host
circleci-signature: v1=4fcc06915b43d8a49aff193441e9e18654e6a27c2c428b02e8fcc41ccc2299f9,v2=...,v3=...

Currently, the latest (and only) signature version is v1. You should only check the latest signature type to prevent downgrade attacks.

The v1 signature is the HMAC-SHA256 digest of the request body, using the configured signing secret as the secret key.

Here are some example signatures for given request bodies:

BodySecret KeySignature
hello worldsecret734cc62f32841568f45715aeb9f4d7891324e6d948e4c6c60c0621cdac48623a
lalalaanother-secretdaa220016c8f29a8b214fbfc3671aeec2145cfb1e6790184ffb38b6d0425fa00
an-important-request-payloadhunter1239be2242094a9a8c00c64306f382a7f9d691de910b4a266f67bd314ef18ac49fa

The following is an example of how you might validate signatures in Python:

import hmac

def verify_signature(secret, headers, body):
    # get the v1 signature from the `circleci-signature` header
    signature_from_header = {
        k: v for k, v in [
            pair.split('=') for pair in headers['circleci-signature'].split(',')
        ]
    }['v1']

    # Run HMAC-SHA256 on the request body using the configured signing secret
    valid_signature = hmac.new(bytes(secret, 'utf-8'), bytes(body, 'utf-8'), 'sha256').hexdigest()

    # use constant time string comparison to prevent timing attacks
    return hmac.compare_digest(valid_signature, signature_from_header)

# the following will return `True`
verify_signature(
    'secret',
    {
        'circleci-signature': 'v1=773ba44693c7553d6ee20f61ea5d2757a9a4f4a44d2841ae4e95b52e4cd62db4'
    },
    'foo',
)

# the following will return `False`
verify_signature(
    'secret',
    {
        'circleci-signature': 'v1=not-a-valid-signature'
    },
    'foo',
)

Event specifications of webhooks

CircleCI currently offers webhooks for the following events:

Event typeDescriptionPotential statusesIncluded sub-entities
workflow-completedA workflow has reached a terminal state“success”, “failed”, “error”, “canceled”, “unauthorized”project, organization, workflow, pipeline
job-completedA job has reached a terminal state“success”, “failed”, “canceled”, “unauthorized”project, organization, workflow, pipeline, job

Common top level keys of webhooks

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

FieldDescriptionType
idID used to uniquely identify each event from the system (the client can use this to dedupe events)String
happened_atISO 8601 timestamp representing when the event happenedString
webhookA map of metadata representing the webhook that was triggeredMap

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.

Common sub-entities of webhooks

The next sections describe the payloads of different events offered with CircleCI webhooks. The schema of these webhook events will 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 contain maps of data for your project, organization, job, workflow and pipeline.

Let us look at some of the common sub-entities that will appear across various webhooks:

Project

Data about the project associated with the webhook event.

FieldAlways present?Description
idyesUnique ID of the project
slugyesString that can be used to refer to a specific project in many of CircleCI’s APIs (e.g. “gh/circleci/web-ui”)
nameyesName of the project (e.g. “web-ui”)

Organization

Data about the organization associated with the webhook event.

FieldAlways present?Description
idyesUnique ID of the organization
nameyesName of the organization (e.g. “circleci”)

Job

A job typically represents one phase in a CircleCI workload (e.g. “build”, “test”, or “deploy”) and contains a series of steps.

Data about the job associated with the webhook event.

FieldAlways present?Description
idyesUnique ID of the job
numberyesAn auto-incrementing number for the job, sometimes used in CircleCI’s APIs to identify jobs within a project
nameyesName of the job as defined in .circleci/config.yml
statusyesCurrent status of the job
started_atyesWhen the job started running
stopped_atnoWhen the job reached a terminal state (if applicable)

Workflow

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

Data about the workflow associated with the webhook event.

FieldAlways present?Description
idYesUnique ID of the workflow
nameYesName of the workflow as defined in .circleci/config.yml
statusNoCurrent status of the workflow. Not included in job-level webhooks
created_atYesWhen the workflow was created
stopped_atNoWhen the workflow reached a terminal state (if applicable)
urlYesURL 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.

Data about the pipeline associated with the webhook event.

FieldAlways present?Description
idYesGlobally unique ID of the pipeline
numberYesNumber of the pipeline, which is auto-incrementing / unique per project
created_atYesWhen the pipeline was created
triggerYesA map of metadata about what caused this pipeline to be created – see below
trigger_parametersNoA map of metadata about the pipeline – see below
vcsNoA map of metadata about the git commit associated with this pipeline – see below

Trigger

Data about the trigger associated with the webhook event.

FieldAlways present?Description
typeyesHow this pipeline was triggered (e.g. “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.

FieldAlways present?Description
circleciyesA map containing trigger information – see below
gitnoA map present when the pipeline is associated with a VCS provider
gitlabnoA map present when the pipeline is associated with a Gitlab trigger

circleci

FieldAlways present?Description
event_timeyesISO 8601 timestamp representing when the pipeline was created
event_typeyesProvider event type that triggered the pipeline (e.g. “push”)
trigger_typeyesTrigger provider (e.g. “gitlab”)
actor_idnoCircleCI user id that the pipeline was attributed to

VCS

FieldAlways present?Description
target_repository_urlnoURL to the repository building the commit
origin_repository_urlnoURL to the repository where the commit was made (this will only be different in the case of a forked pull request)
revisionnoGit commit being built
commit.subjectnoCommit subject (first line of the commit message). Note that long commit subjects may be truncated.
commit.bodynoCommit body (subsequent lines of the commit message). Note that long commit bodies may be truncated.
commit.author.namenoName of the author of this commit
commit.author.emailnoEmail address of the author of this commit
commit.authored_atnoTimestamp of when the commit was authored
commit.committer.namenoName of the committer of this commit
commit.committer.emailnoEmail address of the committer of this commit
commit.committed_atnoTimestamp of when the commit was committed
branchnoBranch being built
tagnoTag 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"
  }
}

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.

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.