Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

With webhooks, get notified about your project's activity on Percy. Use webhooks to send Percy events and data to your servers to customize how Percy integrates with your workflow.

## Creating a webhook configuration

To start receiving webhook notifications, you'll need to create a webhook configuration. Webhooks are configured on a per-project basis. To get started, head over to your project settings page and click the "Add Webhook" button.


When you've created a webhook configuration, you'll see it on the project settings page, along with an icon indicating the status of its most recent delivery. You can create up to 5 webhook configurations.

## Configurable webhook events

We currently offer webhook notifications for the following events:

`ping`A webhook configuration has been created or updated for the current project.
`build_created`A new Percy build was created.
`build_finished`A Percy build finished executing.
`build_approved`A Percy build was approved, either manually by a team member, or automatically due to an auto-approve branch rule or because no visual changes were detected.

If you have ideas for other events you'd like to see, get in touch below.

## Verifying webhook authenticity

If you set a `Secret` in your webhook configuration, we will use it to generate a SHA256 HMAC digest of the payload, and send the digest in the `X-Percy-Digest` header of the webhook request. This secret is never shared and never sent with webhook requests.

You can verify the digest by generating it again with the shared secret and request payload, and comparing your digest to the value in the header.

## Viewing recent webhook deliveries

Once we've sent webhooks to your configured endpoint, we display a list of recent deliveries directly below the webhook configuration.


To view details about a webhook delivery, click its row to expand.


If we weren't able to deliver the webhook successfully, you'll see an error message in the expanded list, including potential remediation steps.


If you're not sure of the meaning of an error message or how to resolve it, please contact support. Common failure reasons include:

  • **Request timeout**: Your server must send a response within 10 seconds or the request will be aborted.

  • **Too many redirects**: Webhook deliveries will accept up to 3 redirects before aborting.

  • **SSL verification failed**: Unless you disable SSL certificate verification if your webhook configuration, we will verify the authenticity of any certificate presented by your server. **Disabling SSL certificate verification is not recommended.**