Skip to main content

Using Webhooks

Creating Webhooks​

You can create a webhook to subscribe to events that occur within your organization.

Webhooks can be created through the Security Scanning Portal interface or via our API. For more details on creating webhooks using the API, refer to the API documentation for webhook endpoints.

Create a webhook

To create a webhook:

  1. On Security Scanning Portal, navigate to My Settings → Webhooks
  2. Click Add Webhook
  3. Provide a name and the Target URL where you'd like to receive event notifications.
  4. Select the events you want to subscribe to (e.g., scan_started, scan_completed).
  5. Optionally, set a webhook secret for validating webhook deliveries (recommended for security).
info

Each webhook is associated with the organization that creates it. This means the selected events will trigger when actions happen to the resources of that organization.

Handling Webhook Deliveries​

Your server should respond with an HTTP 200 status code to acknowledge receipt of the webhook. If our system does not receive a successful response, we will retry delivery up to 3 times, with increasing delays between each attempt.

Validating Webhook Deliveries​

To ensure that the webhook deliveries come from our scanning solution, you should verify the HMAC signature sent in the X-CG-Hook-Signature header.

Here’s how to validate the delivery:

  1. Retrieve the X-CG-Hook-Signature header from the incoming request.
  2. Recompute the HMAC sha256 digest using your webhook secret and the payload.
  3. Compare the recomputed signature with the one provided in the header.
info

The hash signature always starts with sha256= followed by the actual hash.

A ruby code example:

require 'openssl'

def verify_signature(payload_body)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['x-webhook-signature'])
end

Receive Webhooks from Customer's Events​

As a partner, you can receive webhooks when specific customer-related events occur. These events allow you to track activity within your customer organizations without requiring them to interact directly with the scanning solution.

To enable customer-related webhooks just Enable the option “Include Customers' Events”

Include Customers' Events

Best Practices for Using Webhooks​

  • Use HTTPS: Always use secure URLs (https) for webhook endpoints to ensure the data transmitted is encrypted.
  • Use webhook secret and Verify the signature: You should set a webhook secret for your webhook and verify that the signature of each webhook delivery matches the secret. This helps to ensure that the webhook delivery is from our Scanning Solution
  • Validate Payloads: Use the X-CG-Hook-Signature header to validate that the webhook came from our system.
  • Respond Quickly: Ensure that your server responds with a 200 status code as soon as possible, even if additional processing is required later.
  • Retry Handling: Implement idempotency in your webhook processing logic to ensure repeated deliveries don’t cause duplicated actions.
  • Limit Exposure: Use a unique webhook URL for each integration, and consider IP whitelisting to limit access to the endpoint. Subscribe to the minimum number of events: You should only subscribe to the webhook events that you need. This will reduce the amount of work your server needs to do.