Webhooks

Publishing notifications for external listeners

You can enable webhooks for Veza Rules and Alerts and Remediation Proposals to publish event notifications to external applications. When a destination web address is provided, Veza will push a JSON payload with alert information whenever the rule results change. Any entities added or removed since the last result are included in the metadata.

Once you have configured an endpoint to parse the message and trigger an action, webhooks can enable automated processes such as updating an issue tracker, creating a service desk ticket, or sending email or SMS notifications when Veza pushes an alert.

Webhooks can define destination URLs for Workflow events. See [Orchestration Actions and Reminders](../../features/access-reviews/integrations-reminders.md#workflow-Orchestration Actions-with-webhooks) for examples of the payload sent on certification, around the due date, or when a row is approved or rejected.

Configuring a new webhook

Navigate to Integrations > Orchestration Actions > Create Orchestration Action. Enter the required details:

• A Name to identify the webhook

• The destination URL of the application expecting the payload

• Optionally, choose a username and password (Basic authentication) or certificate (bearer token) to include in the authentication header.

The URL must be unique for each new webhook added to Veza.

Adding a webhook to a rule

Webhooks can be attached to rules directly from the rule builder, accessed from the Remediation > Rules panel or by selecting an assessment from Access Search > Saved Queries.

• From Rules, edit an existing rule or create a new one to open the rule builder

• From the Saved Queries list, choose "Create a Rule" from the actions list

• On the Edit Rule screen, select Deliver Alert via Webhook/Email and set an existing webhook

Using the Webhooks panel

You can view, create, and edit webhooks on the Integrations > Orchestration Actions page. For each rule, you can review the:

• Name - provided when the webhook was created

• Rules - any connected rules will be listed. If none are associated, the option to connect a rule will display instead

• Actions - Edit, test, or delete the webhook

Testing a webhook

Click "test" on the webhook builder or configuration screen to validate that a URL has been successfully configured. A sample request will be sent to the destination URL, and a success notification will appear if Veza was able to POST a test notification to the endpoint. You should verify from the endpoint that the payload was delivered as expected.

Since queries are evaluated when a rule is updated, you can also edit the rule and save a change to test the webhook for that rule.

Webhook payloads

Alerts

Sample alert:

{
  "version": "0.9",
  "severity": "high",
  "rule_name": "sample rule",
  "description": "IAM Policies with Full Admin",
  "alert_id": "2004c5c3-0291-44b7-b5be-a237e0e5cc83",
  "rule_id": "70341f2f-1d31-4fc4-9b58-0a72a3bc878e",
  "evaluated_at": 1646076848,
  "compared_at": 1646076810,
  "total_entities_count": 4,
  "query_operator": ">",
  "target_value": 3,
  "query_id": "6c12e00b-31c0-456f-b4dd-867cc5871690",
  "nodes": [
    {
      "id": "arn:aws:iam::345678901234:policy/AdministratorAccess",
      "name": "AdministratorAccess",
      "type": "AwsIamPolicy"
    },
    {
      "id": "arn:aws:iam::23456789012:policy/AdministratorAccess",
      "name": "AdministratorAccess",
      "type": "AwsIamPolicy"
    },
    {
      "id": "arn:aws:iam::123456789012:policy/AdministratorAccess",
      "name": "AdministratorAccess",
      "type": "AwsIamPolicy"
    },
    {
      "id": "arn:aws:iam::456789012345:policy/Staging_AWS_Admin",
      "name": "Staging_AWS_Admin",
      "type": "AwsIamPolicy"
    },
  ],
  "added_nodes": [],
  "removed_nodes": [],
  "cluster_url": "https://sandbox.vezacloud.com"
}

Field	Details
alert_id	Unique alert ID, also shown when exporting the list of alert events to CSV
rule_id	The ID of the rule which triggered the alert
created_at	Alert trigger timestamp
nodes	Contains the node ID and node name for each entity in the most recent assessment
added_nodes	Contains the node ID and name of any new entities since the last time the assessment updated
removed_nodes	Contains the node ID and name of entities included in the last query, but not in the current update

If a username and password are provided, the Base64-encoded string will be included in the header (basic authentication).

Webhooks for Remediation Proposals

Messages for and Remediation Proposals have the keys:

Field	Details
id	Recipe ID
name	"Access Removal" or recipe name
instructions	Contains one or more sets of instructions
instruction_type	Instruction type (not used). 1=default
steps	Instructions to remediate access, using a template.
side_effects	Contains the node ID and name of entities included in the last query, but not in the current update
description	String decribing each permission to a resource that will be changed by following the instructions

Recipe

{
  "id": "RemoveIamRole",
  "name": "Remove IAM Role",
  "details": "Delete the IAM Role from AWS, so that it can no longer be assumed",
  "instructions": [
    {
      "instruction_type": 1,
      "steps": [
        "# Remove an IAM Role with AWS Console\n\n1. Log in to the [AWS Management Console](https://console.aws.amazon.com/) with Account: `00112233445566`.\n2. Type \"IAM\" into the search bar and select the **Roles** IAM feature.\n3. Search for `AleksTestRoleName` on the **IAM** > *Roles* list.\n4. Check to select the `AleksTestRoleName` role.\n5. Click the **Delete** button on upper-right.\n6. Enter the role name in the text input field to confirm and delete the role."
      ]
    }
  ],
  "side_effects": [
    {
      "description": "AwsIamRole \"AleksTestRoleName\" will no longer be able to be assumed"
    }
  ]
}

Remediation Proposal

{
  "id": "AccessRemoval",
  "name": "Access Removal",
  "instructions": [
    {
      "instruction_type": 1,
      "steps": [
        "template line 1: [e-mail]",
        "template line 2: dn44266.us-east-2.aws.snowflakecomputing.com"
      ]
    }
  ],
  "side_effects": [
    {
      "description": "SnowflakeUser principal of ID\ndn44266.us-east-2.aws.snowflakecomputing.com/user/BETTE_NICKA\nwill have permission changes on SnowflakeDatabase resource of ID\ndn44266.us-east-2.aws.snowflakecomputing.com/database/LOCATION\nLOST: {USAGE}\nRESULT: {}\n"
    },
    {
      "description": "SnowflakeUser principal of ID\ndn44266.us-east-2.aws.snowflakecomputing.com/user/ART_VENERE\nwill have permission changes on SnowflakeSchema resource of ID\ndn44266.us-east-2.aws.snowflakecomputing.com/database/LOCATION/schema/STATES\nLOST: {USAGE}\nRESULT: {}\n"
    }
  ]
}