Integrations
Spectral supports four different types of integration:
- Slack for communication
- Jira to open tickets and start your workflow based on the issue which was detected by Spectral
- Monday to create items and start your workflow based on the issue which was detected by Spectral
- Pager Duty for alerts management
- Custom webhooks
The first three settings are global, but you can also define a team-level integration ( see teams section). Custom webhooks are supported globally only for now.
Custom webhook
You can make Spectral notify you on new issues via webhook.
Webhooks can be configured by your account admin in the settings screen under the integrations tab.
You'll need to provide the webhook URL. A signature token will be generated for you, but you can change it.
The signature token is used to sign the content of each notification digitally. We use HMAC with sha-256.
The notification will be sent to the URL you provided as a POST request (json encoded). We expect a 200 OK response.
The content of the request has the following open API schema:
issues:
type: array
items:
type: object
properties:
assetId:
type: string
title: Asset id
description: The asset in which this issue has been discovered
detectorId:
type: string
title: Detector id
description: The detector id
detectorName:
type: string
title: Detector name
description: The detector description
severity:
type: string
title: Severity
description: The severity of this issue (error / warning / info)
uri:
type: string
title: URI
description: View the issue in your source code via this uri
Here's a sample of the content:
{
issues: [
{
assetId: 'github.com/maggie/jelly-sandwich',
detectorId: 'SENF026',
detectorName: 'Ruby On Rails secret token configuration file',
severity: 'error',
uri: 'https://github.com/maggie/jelly-sandwich/blob/ae556dbaa9a8ce4e37a5fe9e95b7823eff79f379/config/initializers/secret_token.rb#L7'
},
{
assetId: 'github.com/maggie/jelly-sandwich',
detectorId: 'CLD001',
detectorName: 'Visible AWS Key',
severity: 'error',
uri: 'https://github.com/maggie/jelly-sandwich/blob/ae556dbaa9a8ce4e37a5fe9e95b7823eff79f379/db/secret2#L4'
},
]
}
Verifying the notification
The signature can be found in the x-spectral-signature
header.
An extra layer of security is added by using the timestamp (ISO format) to create the signature hash. To sign the content, we use this token: [TIMESTAMP]_[SECRET-TOKEN].
To make sure the request hasn't been replayed, you can verify the x-spectral-signature
header in the request is in the last 5 seconds, for example.
You can verify the signature using something like:
// NodeJS example
import crypto from 'crypto'
const verifySignature = (signature, signatureToken, timestamp, payload) => {
const calculatedSignature = crypto
.createHmac('sha256', `${timestamp}_${signatureToken}`)
.update(payload)
.digest('hex')
return (signature === calculatedSignature)
}
You can verify your implementation works like so:
verifySignature('108a388872e723c0b4be83a0b37abb5a55f9a89c17209c47bb11e8064ccd811d', 'myverysecrettoken', '0', 'bar') // returns true
Updated 9 months ago