Webhooks

👍
Covered in this doc

How to configure Percy webhooks

Webhook options and troubleshooting

Get notified about your project's activity on Percy with webhooks. Use webhooks to send Percy events and data to your servers to customize how Percy integrates with your workflow. If you're curious what the webhooks send, these are examples of the various webhook payloads.

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 integrations page and click the "Add Webhook" button.

When you've created a webhook configuration, you'll see it on the integrations 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:

Event	Description
`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.
`build_changes_requested`	The state of a Percy build changed from “Unreviewed” to “Changes requested” because a team member requested changes on a snapshot within it.
`build_unreviewed`	The state of a Percy build changed from “Changes requested” to “Unreviewed” when someone approved the snapshots with requested changes and there are unreviewed snapshots in the build.

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.

require 'openssl'

OpenSSL::HMAC.hexdigest('SHA256', secret, request_payload)

var crypto = require('crypto');

crypto.createHmac('sha256', secret).update(payload).digest('hex');

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.