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