Integrate using generic webhooks

Use webhooks to send alert notifications to any server.

2 minute read

With the StackRox Kubernetes Security Platform, you can send alert notifications as JSON messages to any webhook receiver. When a violation occurs, the StackRox Kubernetes Security Platform makes an HTTP POST request on the configured URL. The POST request body includes JSON-formatted information about the alert.

The webhook POST request’s JSON data includes a v1.Alert object and any custom fields that you configure. To see the details of the v1.Alert object, open the API reference documentation and view the response type for the GetAlert method.

Copy
{
  "alert": {
    "id": "<id>",
    "time": "<timestamp>",
    "policy": {
      "name": "<name>",
      ...
    },
    ...
  },
  "<custom-field-1>": "<custom-value-1>"
}

You can create multiple webhooks, for example, you can create a webhook for receiving all audit logs and a different webhook for alert notifications.

To forward alerts from the StackRox Kubernetes Security Platform to any webhook receiver:

  1. Set up a webhook URL to receive alerts.
  2. Use the webhook URL to set up notifications in the StackRox Kubernetes Security Platform. See Configure the StackRox Kubernetes Security Platform.
  3. Identify policies for which you want to send notifications, and update the notification settings for those policies. See Configure policy notifications.

Configure the StackRox Kubernetes Security Platform

Create a new integration in the StackRox Kubernetes Security Platform by using the webhook URL.

  1. Navigate to Platform Configuration > Integrations.

  2. Under the Plugins section, select Generic Webhook.

  3. Select the New Integration icon.

  4. Enter a name for Integration Name.

  5. Enter the webhook URL in the Endpoint box.

  6. Enter a CA certificate in the CA Cert box, if your webhook receiver is using an untrusted certificate.

    The server certificate used by the webhook receiver must be valid for the endpoint DNS name. You can turn on the Skip TLS Verify toggle to ignore this validation. However, we don’t recommend turning off TLS verification.

  7. (Optional) Turn on the Enable Audit Logging toggle, to receive alerts about all the changes made in the StackRox Kubernetes Security Platform. See Audit Logging for more information.

    We recommend using separate webhooks for alerts and audit logs to handle these messages differently.

  8. To authenticate with the webhook receiver, enter details for:

    • Username and Password for basic HTTP authentication, or
    • custom Header (for example: Authorization: Bearer <access-token>).
  9. Use Extra fields to include additional key-value pairs in the JSON object which the StackRox Kubernetes Security Platform sends. For example, if your webhook receiver accepts objects from multiple sources, you can add "source": "stackrox" as an extra field and then filter on this value to identify all alerts from the StackRox Kubernetes Security Platform.

  10. Select Test (checkmark icon) to send a test message to verify that the integration with your generic webhook is working.

  11. Select Create (save icon) to create the configuration.

Configure policy notifications

  1. Navigate to Platform Configuration > System policies.
  2. Select the check boxes for one or more policies for which you want to send alerts.
  3. Select Enable Notifications or Actions > Enable Notification (depends upon the StackRox Kubernetes Security Platform version you are using).
  4. In the Enable Notifications dialog, select the check box for your webhook receiver name (same as the Integration Name). If you haven’t configured any other integrations, you’ll see the message No notifiers configured!.
    Configure policy notifications
    Configure policy notifications
  5. Select Enable.
  • The StackRox Kubernetes Security Platform sends notifications on an opt-in basis. To receive notifications, you must first assign a notifier to the policy.

  • Notifications are only sent once for a given alert. If you have assigned a notifier to a policy, you won’t receive a notification unless a violation generates a new alert. The StackRox Kubernetes Security Platform creates a new alert when:

    • a policy violation occurs for the first time in a deployment, or
    • a runtime-phase policy violation occurs in a deployment after you resolved the previous runtime alert for that policy in that deployment.

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.