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.
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.
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.
Related Topics
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
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!