Using Webhooks

One-Click Least Privilege. Zero Disruption.

© 2025 Sonrai Security. All rights reserved.

Overview

Cloud Permissions Firewall (CPF) has the ability to integrate with external tools and services by registering webhooks that get triggered by Sonrai events.

Webhooks allow you to do things like:

• send notifications to your SIEM, so security teams have visibility into granted/denied requests for access
• trigger a ticketing or workflow process based on specific Sonrai events
• simplify audit and compliance tracking by logging specific types of action to your audit repository
• build custom automations (such as AWS Lambda or Azure Functions) that react when new controls are deployed

There are a variety of Sonrai events available for your webhook to reference.

---

Create a Webhook Integration

Using the Sonrai GraphQL API, creating a new webhook integration registered to use your endpoint is fast and easy: just submit a SonraiWebhookCreate mutation similar to:

mutation createWebhook {
  SonraiWebhookCreate(
    input: {
      url: "<webhook_url>"
      method: "POST"
      authed: false
      filters: [{ eventName: "jit.*" }, { eventName: "pond.*" }]
    }
  ) {
    webhookId
    message
    success
  }
}

Sample successful response:

{
  "data": {
    "SonraiWebhookCreate": {
      "webhookId": "80379025-1f6b-4fa0-b89a-2593af983bb5",
      "message": "Webhook integration created successfully",
      "success": true
    }
  },
  "extensions": {}
}

This example integration includes a wildcard (*) in the filter values, ensuring that notifications are sent to the registered URL when any JIT or PoD events occur in Cloud Permissions Firewall. See the table below for more information about the fields in the SonraiWebhookCreate mutation:

Field	Value
url	HTTPS link to your webhook service.
method	POST is the only HTTP method accepted for webhooks.
authed	Boolean value, indicating whether your webhook service requires authentication. If set to true, then the auth field must also be populated.
auth	Contains either a bearer token, or basic authorization details for the webhook service. This field is required if the authed field is set to true.
filters	An array of event names that will trigger the registered webhook. A filter can contain one wildcard; for example, {eventName: "jit.*"} reacts to any JIT event. See Available Webhook Events for a list of available Sonrai events.

Authorization Methods

The sample SonraiWebhookCreate mutation above didn't require any authorization - but many external applications will require authorization when called by the webhook you create. In this case, set the authed field to true and then include one of the following authorization methods in your mutation:

Basic Authorization

authed: true
auth: {
  basicAuth:{
    username: "<USERNAME>"
    password: "<PASSWORD>"
  }
}

Bearer Token

authed: true
auth: {
  bearerToken: {
    token: "<TOKEN>"
  }
}

---

List Existing Webhook Integrations

To see a list of existing webhook integrations, you can use this GraphQL query:

query existingWebhooks {
  IntegrationRegistrations(
    where: {
      type: { op: EQ, value: "Notification" }
      name: { op: LIKE, value: "webhook%" }
    }
  ) {
    count
    items {
      id
      type
      name
      description
      platformMetadata
    }
  }
}

Sample successful response:

{
  "data": {
    "IntegrationRegistrations": {
      "count": 1,
      "items": [
        {
          "id": "80379025-1f6b-4fa0-b89a-2593af983bb5",
          "type": "Notification",
          "name": "webhook_%3Cwebhook_url%3E",
          "description": "Webhook Integration: POST %3Cwebhook_url%3E",
          "platformMetadata": {
            "key": "<webhook_url>",
            "url": "<webhook_url>",
            "authed": false,
            "method": "POST",
            "filters": [
              {
                "eventName": "<event_name>"
              }
            ],
            "platform": "Webhook"
          }
        }
      ]
    }
  },
  "extensions": {}
}

info

Chatops notifications for Slack are also saved with "Notification" as the type. Looking for a partial match in name limits your query results to only webhooks instead of showing all registered notifications.

---

Remove A Webhook Integration

Removing a webhook also is handled by creating a GraphQL mutation.

1. Use the query above to retrieve a list of existing webhooks.
2. Confirm the ID for the webhook integration that you want removed.
3. Run the sample mutation below, replacing <integration_id> with the ID you confirmed earlier:

mutation RemovebWehooks {
  SonraiWebhookRemove(input: { id: "<integration_id>" }) {
    success
    message
  }
}

Sample successful response:

{
  "data": {
    "SonraiWebhookRemove": {
      "success": true,
      "message": "Webhook integration removed"
    }
  },
  "extensions": {}
}