Set up integrations using webhooks - Endor Labs Documentation

Webhooks enable real-time communication between different systems or applications over the internet. They allow one application to send data to another application as soon as a specific event or a trigger occurs. Use webhooks to integrate Endor Labs with applications such as Slack, Microsoft Teams or more, and instantly get notified about projects when scans violate your configured policies. When events occur, Endor Labs sends HTTPS POST requests to URLs of your configured events, with all the information you need.

Configure a webhook integration

Set up a custom integration with Endor Labs webhooks.

Select User menu > Integrations from the left sidebar.
Under Notifications, click Add on the Webhook card. If you already have a webhook integration, click Manage instead.
Click Add Notification Integration. Send Notifications to Webhook appears.
Enter a Name and Description for this integration.
In URL endpoint for webhook, enter the URL of your webhook receiver.
Choose an Auth method of None, Basic, or API Key, then enter its credentials. Basic authentication uses Username and Password. API key authentication uses API Key. Make sure the credentials grant permission to post to your receiver.
If you chose Basic or API Key, HMAC signing is on by default. Enter an HMAC Shared Key, or select Disable HMAC Integration Check to turn it off. When HMAC is on, Endor Labs signs the request body and sends the signature in the X-Endor-HMAC-Signature header so your receiver can verify that the request is authentic. HMAC is not available for None auth.
Optional: Under Custom Headers, click Add Header, then enter a Header name and Header value. You can add up to 20 headers.
Use custom headers to pass vendor-specific API keys required by your webhook receiver. Endor Labs includes custom headers in every webhook request, regardless of the authentication method used.
Optional: Select Propagate this notification target to all child namespaces to make this integration available in child namespaces.
Click Add Notification Integration to save the integration.

Associate an action policy with the webhook

You can create action policies to trigger webhook notifications when a scan matches policy conditions. For example, send a webhook notification when there is a critical or high vulnerability. To send a webhook when a scan produces matching findings, create an action policy with a Send Notification action that targets your webhook integration. For the full procedure, see Create an action policy. The webhook-specific choices are:

Under Choose an Action, select Send Notification.
From Select notification targets, choose the webhook integration you created.

From Select aggregation type, choose how findings are grouped into notifications.

None (Notify for each Finding) sends a separate notification for each finding.
Project sends a single notification for all findings in a project.
Dependency sends a notification for every dependency.
Dependency per Package Version sends a notification for every unique combination of dependency and package version.

Endor Labs webhook payload

Endor Labs provides the following webhook payload, that you can customize for your needs. You can view all possible payload information in GetFindings REST API endpoint. Expand the spec section in the API response to view all the information. See the following sample notification payload.

If you use Endor Labs with an EU tenant, use https://app.eu.endorlabs.com instead of https://app.endorlabs.com.

{
 "data": {
  "message": "4 findings discovered for project endorlabs/monorepo",
  "projectURL": "https://app.endorlabs.com/t/<your-namespace>/projects/<project_uuid>",
  "policy": {
   "name": "Webhook vuln",
   "url": "https://app.endorlabs.com/t/<your-namespace>/policies/actions?filter.default=Webhook+vuln"
  },
  "findings": [
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
    "severity": "FINDING_LEVEL_MEDIUM",
    "dependency": "semver@7.5.0",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440000"
   },
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440001",
    "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
    "severity": "FINDING_LEVEL_MEDIUM",
    "dependency": "semver@7.3.8",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440001"
   },
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440002",
    "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
    "severity": "FINDING_LEVEL_MEDIUM",
    "dependency": "semver@5.7.1",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440002"
   },
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440003",
    "description": "GHSA-c2qf-rxjj-qqgw: semver vulnerable to Regular Expression Denial of Service",
    "severity": "FINDING_LEVEL_MEDIUM",
    "dependency": "semver@6.3.0",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440003"
   }
  ]
 }
}

In the payload, replace <your-namespace> and <project_uuid> with the values from your Endor Labs tenant. The identifier in each findingURL matches that finding’s uuid.

Payload variations by notification event

Endor Labs sends a webhook for three notification events. The data.message text and the presence of data.findings change with the event.

Findings discovered: Endor Labs sends the payload shown above. The data.message field reads <count> findings discovered for project <project> and data.findings lists every finding.
New findings added: A later scan finds additional findings. The data.message field reads <count> new findings discovered for project <project> and data.findings lists only the new findings.
Findings resolved: A scan resolves all findings. The data.message field reads All findings resolved for project <project> and the payload omits the data.findings array.

The data.policy object is present only when an action policy triggers the notification. The following example shows the payload when a later scan adds new findings. The data.findings array lists only the new findings.

{
 "data": {
  "message": "2 new findings discovered for project endorlabs/monorepo",
  "projectURL": "https://app.endorlabs.com/t/<your-namespace>/projects/<project_uuid>",
  "policy": {
   "name": "Webhook vuln",
   "url": "https://app.endorlabs.com/t/<your-namespace>/policies/actions?filter.default=Webhook+vuln"
  },
  "findings": [
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440004",
    "description": "GHSA-jf85-cpcp-j695: Prototype Pollution in lodash",
    "severity": "FINDING_LEVEL_CRITICAL",
    "dependency": "lodash@4.17.4",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440004"
   },
   {
    "uuid": "550e8400-e29b-41d4-a716-446655440005",
    "description": "GHSA-35jh-r3h4-6jhm: Command Injection in lodash",
    "severity": "FINDING_LEVEL_HIGH",
    "dependency": "lodash@4.17.4",
    "package": "endorlabs-vscode-extension@1.5.0",
    "findingURL": "https://app.endorlabs.com/t/<your-namespace>/findings/550e8400-e29b-41d4-a716-446655440005"
   }
  ]
 }
}

The following example shows the payload when a scan resolves all findings. The payload omits the data.findings array.

{
 "data": {
  "message": "All findings resolved for project endorlabs/monorepo",
  "projectURL": "https://app.endorlabs.com/t/<your-namespace>/projects/<project_uuid>",
  "policy": {
   "name": "Webhook vuln",
   "url": "https://app.endorlabs.com/t/<your-namespace>/policies/actions?filter.default=Webhook+vuln"
  }
 }
}

Use Endor Labs webhooks to integrate with Slack

If you use Slack as a collaborative tool, integrate Slack channels using webhooks in Endor Labs to publish notifications as messages in the respective channels.

Configure a webhook integration
Endor Labs webhook payload
Use Endor Labs webhooks to integrate with Slack

Create incoming webhooks in Slack

Create an incoming webhook to your Slack channel to enable Endor Labs to post notifications in the channel. The webhook provides a unique URL for integrating the channel in Endor Labs. To send messages into Slack using incoming webhooks, see Slack Integration If you have already created an incoming webhook in the channel, copy the unique URL and integrate the channel in Endor Labs.

Customize webhook notification templates

Endor Labs provides you with a default template with standard information for the webhook message. You can use the default template or you can choose to edit and customize this template to fit your organization’s specific requirements. You can also create your own custom templates using Go Templates.

Select User menu > Integrations from the left sidebar.
Under Notifications, click Manage on the Slack card to view the configured notification integrations.
Choose one, click the ellipsis on the right side, and click Edit Template.
Make required changes to any of the following templates and click Save Template.
- Open - This template applies when Endor Labs raises new notifications.
- Update - This template applies when an existing notification updates, such as when findings change.
- Resolve - This template applies when all findings reported by the notification resolve.
Click Restore to Default to revert the changes.
Use the download icon on the top right corner to download this template.
Use the copy icon to copy the information in the template.

Data model

To create custom templates for Webhook notifications, you must understand the data supplied to the template. See the protobuf specification NotificationData message used for the templates. To understand Project, Finding, PackageVersion and RepositoryVersion definitions used in this protobuf specification, see:

See the following specification to understand a few additional functions available to the template. You can access these functions by using their corresponding keys.

Webhook handler example for Slack

Create a webhook handler or a cloud function to receive webhook requests generated by Endor Labs, authorize the request, and post messages to your Slack channel. See the following code sample hosted as a cloud function or a webhook handler.

// Package p contains an HTTP Cloud Function that receives Endor Labs webhook
// notifications, verifies the HMAC signature, and posts a message to Slack.
package p

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
)

// WebhookMessage is the default Endor Labs webhook payload.
type WebhookMessage struct {
	Data Payload `json:"data"`
}

type Payload struct {
	Message    string    `json:"message"`
	ProjectURL string    `json:"projectURL"`
	Policy     Policy    `json:"policy"`
	Findings   []Finding `json:"findings"`
}

type Finding struct {
	UUID              string `json:"uuid"`
	Description       string `json:"description"`
	Severity          string `json:"severity"`
	Dependency        string `json:"dependency,omitempty"`
	Package           string `json:"package,omitempty"`
	RepositoryVersion string `json:"repositoryVersion,omitempty"`
	FindingURL        string `json:"findingURL"`
}

type Policy struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

// hmacSharedKey is the HMAC Shared Key you configured on the webhook integration.
const hmacSharedKey = "<your-hmac-shared-key>"

// HandleWebhook verifies the request signature, then posts the notification to Slack.
func HandleWebhook(w http.ResponseWriter, r *http.Request) {
	// Read the raw body first. Endor Labs signs these exact bytes, so verify the
	// signature before decoding the JSON.
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "unable to read request body", http.StatusBadRequest)
		return
	}

	// Endor Labs signs the raw body with HMAC-SHA256 and sends the
	// base64-encoded signature in the X-Endor-HMAC-Signature header.
	if !validSignature(body, r.Header.Get("X-Endor-HMAC-Signature"), hmacSharedKey) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}

	var message WebhookMessage
	if err := json.Unmarshal(body, &message); err != nil {
		http.Error(w, "unable to decode payload", http.StatusBadRequest)
		return
	}

	text := fmt.Sprintf("%s which violates policy %s", message.Data.Message, message.Data.Policy.Name)
	if err := sendMessageToSlack(text); err != nil {
		log.Printf("unable to post to Slack: %v", err)
		http.Error(w, "unable to post to Slack", http.StatusInternalServerError)
		return
	}
}

// validSignature recomputes the HMAC over the raw body and compares it against
// the received signature in constant time.
func validSignature(body []byte, receivedSignature, sharedKey string) bool {
	mac := hmac.New(sha256.New, []byte(sharedKey))
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(receivedSignature))
}

// sendMessageToSlack posts a message to a Slack incoming webhook.
func sendMessageToSlack(text string) error {
	// Replace this with the incoming webhook URL from your Slack app.
	slackWebhookURL := "https://hooks.slack.com/services/<your-slack-webhook>"

	body, err := json.Marshal(map[string]string{"text": text})
	if err != nil {
		return err
	}

	resp, err := http.Post(slackWebhookURL, "application/json", bytes.NewReader(body))
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	return nil
}

​Configure a webhook integration

​Associate an action policy with the webhook

​Endor Labs webhook payload

​Payload variations by notification event

​Use Endor Labs webhooks to integrate with Slack

​Create incoming webhooks in Slack

​Customize webhook notification templates

​Data model

​Webhook handler example for Slack

Configure a webhook integration

Associate an action policy with the webhook

Endor Labs webhook payload

Payload variations by notification event

Use Endor Labs webhooks to integrate with Slack

Create incoming webhooks in Slack

Customize webhook notification templates

Data model

Webhook handler example for Slack