Skip to main content

Webhooks

Learn how to configure webhooks to receive notifications about your project activity

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.

Create Webhook

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.

Copy icon Copy snippet
Copy icon Copy snippet

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.

View recent webhook deliverables

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

Webhook delivery details

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

Webhook delivery - error

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.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy