Webhooks Management

Prerequisites

Ensure that you have permission on the Delinea Platform to manage webhooks:

  • Permission name: Manage Webhooks

  • Permission string: delinea.platform/webhooks/manage

For more information about permissions, see the Platform Permissions table.

 

Creating a Webhook

  1. Navigate to Settings > General settings > Webhooks. The Webhooks page opens.

  2. Select Create Webhook.

  3. On the Create Webhook page, complete the following fields:

    • Name: Enter a name.

    • Endpoint URL: Enter the destination URL for the webhook payload.

    • Description: This is an optional field where you can add descriptive information.

    • Webhook State: This check box, selected by default, enables the webhook (selected) or disables it (deselected). If you disable a webhook and later re-enable it, only subsequent events will be sent.

Triggers

In the Triggers section, complete the following fields to subscribe your webhook to specific events. This allows you to receive notifications only for those events you are interested in:

  • Service: Select one or more services.

  • Level: Select one or more levels.

Webhooks are global and applied across all entities. Based on the selection, every new event will be triggered.

Custom Headers

In the Customer Headers section, complete the following fields to add optional custom HTTP headers for additional request configuration:

  • Key: This represents the name of the header you want to add. It serves as an identifier for the data you are sending in the header.

  • Value: This represents the content or value associated with the header key. It is the data you intend to send with the webhook request under the specified header key.

Click Save to create your webhook with the specified configurations.

Managing Webhooks

To access available webhooks or to create a new one, navigate to Settings > Webhooks.

On the Webhooks page, two tabs are available: Webhooks and Logs:

  • Webhooks: On the Webhooks tab, you can see all the available webhooks. The following columns are displayed:

    • Name: The name of the webhook.

    • Triggers: The specific platform events or actions that trigger the webhook. For example, this could be user logins, secret access, or policy changes that prompt the webhook to be activated.

    • Endpoint URL: The URL to which the webhook sends event data. This is the endpoint specified when configuring the webhook where platform events are delivered.

    • Created By: The user who created the webhook. This helps identify the origin of the webhook setup, especially in team or multi-user environments.

    • Created At: The timestamp indicating when the webhook was initially created. This helps track when the webhook was set up.

    • State: The status or state of the webhook. It might indicate whether the webhook is active or inactive (e.g., "Enabled," "Disabled").

    • Last Run Status: The status of the most recent webhook execution, showing whether it was successful or encountered an error (e.g., "Success," "Failed," "Pending").

  • Logs: On the Logs tab, the following columns are displayed:

    • Name: The name or identifier of the webhook event or configuration.

    • Status: The status of the webhook, indicating whether it was successfully triggered or encountered an issue (e.g., success, failure).

    • Triggers: The specific events or actions that allow you to receive notifications only for those events you are interested in.

    • Created By: The user or account that created the webhook configuration.

    • Sent At: The timestamp indicates when the webhook event was sent to the specified endpoint.

In both tabs, you can select the grid button to display only the columns you wish to see.

To manage your webhooks:

  1. Navigate to Settings > General settings > Webhooks. The Webhooks page opens.

  2. Select your webhook from the list.

  3. Select Edit to change the configurations for the webhook.

  4. Click the Actions drop-down menu.

    From the Actions dropdown you can select:

    • Delete to delete the selected webhook

    • Test Webhook to test the created webhook

    • View Webhook Logs to display the webhook logs.

Webhook Logs

There are three ways to view the webhook logs from the Webhooks page:

  • Click to open the desired webhook, click the Actions drop-down menu, and choose View Webhook Logs (see image above).

  • Select the Logs tab.

  • Hover over the webhook row, click the ellipses (...) that appears, and select the View Webhook Logs option. Here you can also delete the webhook by selecting the Delete option, or see details by selecting the View Details option.

To download webhook logs:

  1. Select the Download icon.

    The Download page opens.

  2. On the Download page, specify the logs to download using the fields presented:

  • Records: Specify the number of records to include in the logs.

  • File Name: Enter a name for the webhook log file to make it easier to locate.

  • Date Format: Select your preferred date format from the dropdown menu.

Verifying a Webhook

Complete the following steps to validate the incoming webhook payloads against the token and verify that they are from Delinea and have not been tampered with:

  1. Navigate to Settings > General settings > Webhooks. The Webhooks page opens.

  2. Select Verify Webhook.


    The Verify Webhook page opens.


  3. On the Verify Webhook page, copy the secret token and store it in a secure and accessible server location.
    Delinea will use your secret token to create a hash signature that is sent to you with each payload. The hash signature will appear in each delivery as the value of the X-Token header.

  4. Select Got it! to close the page.

Calculating Hash

In your code that handles webhook deliveries, calculate a hash using your secret token. Then compare the hash sent by Delinea with the expected hash you calculated to ensure that they match.

Python Example

You can use the following verify_signature function and call it when you receive a webhook payload:

Copy
Python Example
import base64 

import hashlib 

import hmac 

import json 


def verify_signature(payload_body: dict, secret_token: str, signature_header: str): 

    """Verify that the payload was sent from Delinea by validating SHA256. 


    Raise and return 403 if not authorized. 


    Args: 

        payload_body: original request body to verify (request.body()) 

        secret_token: Delinea app webhook token (WEBHOOK_SECRET) 

        signature_header: header received from Delinea(x-hub-signature-256) 

    """ 

    if not signature_header: 

        raise HTTPException(status_code=403, detail="x-signature header is missing!") 

    payload = json.dumps(payload_body).encode("utf-8") 

    signature = base64.b64decode(signature_header) 

    digest = hmac.new(secret_token.encode("utf-8"), msg=payload, digestmod=hashlib.sha256).digest() 

    if not hmac.compare_digest(digest, signature): 

        raise HTTPException(status_code=403, detail="Request signatures didn't match!")