Guides

Integrations

Suggest Edits

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
  • Events Webhook Integration

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'
    },
  ]
}

Events Webhook Integration

The Events Webhook Integration feature allows users to receive notifications when the state of an issue or asset changes.
This feature ensures that users are promptly informed about updates, facilitating better monitoring and management of their resources.

In some cases, the count of changes can be significant, and to reduce the number of events triggered, we aggregate the events and create chunks of these events.

Event Payloads

The following sections describe the structure of the event payloads for changes in issues or assets, and for ingest completion.
All events include the name of the event and the id or ids of the resource and the time of the event. To retrieve all the data associated with these resource IDs, you can refer to our API documentation.

Please note that there is a 10-second timeout set on your webhook. This means that your webhook endpoint must respond within 10 seconds of receiving the notification; otherwise, the request will time out. Ensure that your webhook processing logic is efficient to handle incoming events within this time frame.

Changes in Issue or Asset

When an issue or asset changes, an event is triggered with the following payload:

{
  "name": String,
  "ids": [String],
  "time": YYYY-MM-DDTHH:mm:ss.SSSZ
}
  • name: Specifies the type of change event. Possible values are:
  • issues_updated
  • assets_deleted
  • ids: A list of IDs that changed, the ids in issues_updated are issues ids, the the ids in assets_deleted are asset ids.
  • time: The time when the event occurred.

Ingest Completion

The ingest process involves transmitting the results detected by the Spectral scanner to our servers.
Once the ingest process is completed, an event is triggered with the following payload:

{
  "name": String,
  "id": String,
  "issues_deleted_count": number,
  "issues_created_count": number,
  "issues_updated_count": number,
  "issues_resolved_count": number,
  "time": YYYY-MM-DDTHH:mm:ss.SSSZ
}
  • name: will be asset_ingest_completed
  • id The asset ID related to the ingest event.
  • issues_deleted_count: Indicates the count of deleted issues in the ingest.
  • issues_created_count: Indicates the count of new issues in the ingest.
  • issues_updated_count: Indicates the count of updated issues in the ingest, excluding the "resolved" status change, which counts in 'issues_resolved_count'.
  • issues_resolved_count: Indicates the count of resolved issues ih the ingest event.
  • time: The time when the event occurred.

Testing Your Webhook Integration

To ensure that your webhook integration is correctly set up and functioning as expected, we provide a Test Button feature.
This allows you to send a test notification to your configured webhook endpoint, simulating a real event.

How to Use the Test Button

  • Click the Test Button: In the webhook configuration section, you will find a Test Button. Clicking this button will trigger a test notification to be sent to your configured webhook URL.
  • Verify the Test Notification: Once you click the Test Button, a sample notification will be sent to your webhook endpoint. Check your webhook endpoint to ensure it receives the test payload correctly. This will help you confirm that your webhook is properly configured and able to handle incoming requests.

Comparison of Events Webhook Integration and Custom Webhook Features

Events Webhook Integration notifies users of changes in the state of issues or assets.
It covers a range of event types, including updates to issues and assets (such as issues_updated, issues_created, and assets_updated).
Additionally, it notifies users when the ingest process is completed, indicating if any changes occurred during the process. The payload for Events Webhook Integration contains only the resource IDs of the changed items.

On the other hand, Custom Webhook notifies users only of new issues via webhook. The payload for Custom Webhook contains detailed issue data, including information such as asset ID, detector ID, detector name, severity, and URI to view the issue in the source code.

Verifying Signature

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 about 2 months ago