Webhooks overview

Cloud

Server v4.x

Server v3.x

Build a custom dashboard to visualize or analyze workflow/job events.
Send data to incident management tools (such as PagerDuty).
Use tools like Airtable to capture data and visualize it.
Alert when a workflow is cancelled, then use the API to rerun the workflow.
Trigger notification systems to alert people when workflows/jobs complete.
Build your own automation plugins and tools.

Introduction

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.

Quickstart

There is a limit of 5 webhooks per project.

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:

Visit a specific project you have set up 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. 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.

Field	Required?	Intent
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 ¹
Secret token	N	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

¹Only leave this unchecked for testing purposes.

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

Webhook requests may be duplicated. To deduplicate (prevent requests from being duplicated for a specific event), use the id property in the webhook payload for identification.

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 Name	Value
`content-type`	`application/json`
`user-agent`	A string indicating that the sender was CircleCI (`CircleCI-Webhook/1.0`).
`circleci-event-type`	The type of event, (`workflow-completed`, `job-completed`, etc)
`circleci-signature`	When present, this signature can be used to verify that the sender of the webhook has access to the secret token.

Validate webhooks

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:

Body	Secret Key	Signature
`hello world`	`secret`	`734cc62f32841568f45715aeb9f4d7891324e6d948e4c6c60c0621cdac48623a`
`lalala`	`another-secret`	`daa220016c8f29a8b214fbfc3671aeec2145cfb1e6790184ffb38b6d0425fa00`
`an-important-request-payload`	`hunter123`	`9be2242094a9a8c00c64306f382a7f9d691de910b4a266f67bd314ef18ac49fa`

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

Next steps

See the Webhooks reference page for key definitions and sample payloads.
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.