Integrate with Chromatic
Integrate Chromatic into your existing tools and services with webhooks.
Slack notifications
Post a message in a designated Slack channel when a build’s status changes. Follow the instructions below to connect a Chromatic project to a Slack channel using a webhook. You can repeat this process to create webhook URLs for multiple channels.
- Sign in to Slack and add the Incoming WebHooks app to your workspace.
- Choose the channel where you want Chromatic to post notifications then click “Add Incoming WebHooks integration”.
- Set the icon to the custom Chromatic icon found below.
- Set the “Customize name” to “Chromatic”.
- Copy the webhook URL. It’s formatted like this
https://hooks.slack.com/services/...
- Go to your Chromatic project and click the manage tab in the sidebar. Scroll down to “Integrations”.
- Click the “Add webhook” button in the Slack section then paste the webhook from step 4 into the input.
- 🎉 You’ll now receive notifications in your Slack channel.
Please note that Slack notifications are not posted for passed builds.
The custom icon:
Custom webhooks
Connect Chromatic to other services that support webhooks to script custom behavior and automate advanced workflows.
- Go to your Chromatic project and click the manage tab in the sidebar. Scroll down to “Integrations”.
- Click the “Add webhook” button in the custom webhook section, then paste your webhook into the input.
When a build’s status changes, we’ll send a POST
request to your webhook with a body that looks like this:
{
"event": "build-status-changed",
"build": {
"number": 123,
"result": "SUCCESS",
"status": "BUILD_ACCEPTED",
"webUrl": "https://www.chromatic.com/build?appId=5dca7f6a6ce19b00201febb7&number=123",
"branch": "main",
"commit": "f6f223efb3b99b83ac3b0b6ece9f9620619933c1",
"committerName": "John Doe",
"storybookUrl": "https://5dca7f6a6ce19b00201febb7-yubzntxvow.chromatic.com/",
"changeCount": 12,
"componentCount": 42,
"specCount": 100,
"projectName": "my-repo"
}
}
The event
name is constant, but the build
data will vary.
How to integrate custom webhooks
Chromatic will make a post request with the above body to the designated webhook URL. That gives you flexibility to catch the webhook response and customize it to fit the service you’re integrating with.
Most customers set up a simple proxy app to customize the webhook message. Below are some starter projects for known Git providers that use Express as a proxy to help you integrate with Chromatic.
Git provider | Repository |
---|---|
GitHub | Source |
GitLab | Source |
Signed Webhooks
Chromatic supports signed webhooks. Here is an example code of handling them: signed-webhook-examples. Please contact us via in-app chat or email to enable signed webhooks on your account.
Result and status codes
Update | result |
status |
Legacy status |
---|---|---|---|
🌕 Ready for review (has changes) | SUCCESS |
PENDING |
BUILD_PENDING |
🟢 Passed (no changes) | SUCCESS |
PASSED |
BUILD_PASSED |
🟢 Accepted | SUCCESS |
ACCEPTED |
BUILD_ACCEPTED |
🔴 Denied | SUCCESS |
DENIED |
BUILD_DENIED |
🔴 Broken | CAPTURE_ERROR |
BROKEN |
BUILD_FAILED |
⚫️ Canceled | SYSTEM_ERROR |
CANCELLED |
BUILD_ERROR |
⚫️ Error | SYSTEM_ERROR |
FAILED |
BUILD_ERROR |
⚫️ Timed out | TIMEOUT |
FAILED |
BUILD_ERROR |
If you’ve been using a custom webhook for a long time, or used to have one in the past, your project might still be configured to receive the legacy status
values.
You can either continue to use the old values, or contact us so we can switch your project over to the new values. Removing and recreating your webhook will not automatically update you to the new format.