# Custom Webhooks You can enable webhooks for Veza [Rules and Alerts](/4yItIzMvkpAvMVFAamTf/features/insights/rules-and-alerts.md) to publish event notifications to external applications. When a destination URL is provided, Veza will push a JSON payload containing alert details whenever the rule results change. Any entities added or removed since the last evaluation are included in the payload. 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. {% hint style="info" %} **For ServiceNow or Jira ticket creation**, use the dedicated [ServiceNow](/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/servicenow.md) or [Jira](/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/jira.md) Veza Action rather than configuring a generic webhook. Native integrations provide reliable ticket creation with built-in error handling. Use generic webhooks for custom targets or automation workflows that are not covered by a native integration. {% endhint %} Webhooks can trigger remediation actions when a row is approved or rejected. See [Veza Actions and Reminders](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/veza-actions.md) for examples of the unique payloads based on the review due date, or when rows are signed off. **Domain Filtering for Veza Actions**: Administrators can configure a list of approved domains for email and webhook Veza Actions on the *System Settings* page. Messages are not sent to unapproved domains when this option is enabled. ### Configuring a new webhook Navigate to **Integrations** > **Veza Actions** > *Create Veza Action*. Enter the required details: * A **Name** to identify the webhook * The destination **URL** of the application expecting the payload * Optionally, configure authentication by selecting the appropriate authentication method: * **Basic Authentication**: Select "Basic" from the authentication type dropdown and enter a username and password * **Token Authentication**: Select "Token" from the authentication type dropdown and provide a token value * Optionally, select an **Insight Point** if you need to relay webhooks to a private network destination (see [Webhook Relay for private network destinations](#webhook-relay-for-private-network-destinations)) {% hint style="info" %} The URL must be unique for each new webhook added to Veza. {% endhint %} ### Adding a webhook to a rule Webhooks can be attached to rules by opening the [rule builder](/4yItIzMvkpAvMVFAamTf/features/insights/rules-and-alerts.md), accessed from the **Rules and Alerts** page (click the **Alerts** bell icon in the top toolbar), or by selecting an assessment from **Access Visibility** > *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** > *Veza 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 is able to POST a test notification to the endpoint. You should verify from the endpoint that the payload was delivered as expected. You can also test the webhook by editing a rule and saving changes. Queries are evaluated when a rule is updated. ## Webhook payloads ### Alerts Sample alert: ```yaml { "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 | ## Authentication Headers Veza supports two authentication methods for webhooks: ### Basic Authentication When configuring a webhook with Basic Authentication, provide both a username and password. Veza will include a Basic Authentication header with the Base64-encoded credentials in the format `username:password`: ```yml Authorization: Basic dXNlcjoxMjM= ``` In the example above, `dXNlcjoxMjM=` is the Base64 encoding of `user:123`. Additionally, when using Basic Authentication, the credentials will also be included as separate header fields: ```yml php-auth-user: user php-auth-pw: password ``` ### Token Authentication When configuring a webhook with Token Authentication, provide a token value. Veza will include it directly in the Authorization header: ```yml Authorization: 123 ``` Where `123` is the token value you configured. {% hint style="info" %} Choose the authentication method that matches your webhook endpoint's requirements: * Use **Basic Authentication** when your endpoint expects credentials in the standard HTTP Basic Auth format and needs both username and password * Use **Token Authentication** when your endpoint expects a simple token in the Authorization header (commonly used with API keys or custom authentication schemes) {% endhint %} ## Webhook Relay for private network destinations By default, Veza sends webhooks directly from the Veza cloud platform to the configured destination URL. However, you may need to send webhooks to internal systems, on-premises services, or private endpoints that are not accessible from the public internet. ### Using an Insight Point for Webhook Relay Veza [Insight Points](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) can relay webhook requests to destinations within your private network. When webhook relay is configured on an Insight Point, the Insight Point acts as a secure intermediary, forwarding webhook payloads from the Veza platform to your internal destinations. **When to use webhook relay:** * Send webhooks to internal systems not accessible from the public internet * Route webhook traffic through your private network for security or compliance requirements * Test webhook integrations using private endpoints during development **Configuration:** Webhook relay must be configured on the Insight Point deployment. The configuration process varies by deployment method: * [OVA Deployment](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/ova-v2.md) * [Install Script](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-install-script.md) * [Kubernetes/Helm](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-kubernetes.md) * [EC2](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-ec2.md) * [Azure Container Instances](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/azure.md#step-4a-configure-webhook-relay-optional) For detailed configuration instructions, consult the [Insight Point documentation](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md#webhook-relay). **Security:** Webhook relay is disabled by default on Insight Points. When enabled, you must explicitly specify which destination hosts are allowed to receive webhook requests. Only allowed destinations will be able to receive webhooks through the relay. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.