Skip to main content

Cyware Orchestrate

Configure Webhooks

Webhooks are used to send data in JSON format from an external application to Orchestrate using a webhook URL to trigger events. Analysts can run Playbooks by configuring the same label to Playbook and events. Analysts can manage the usage of webhook URLs to specific IP addresses by adding IP addresses to the allowed list.

For more information on the use case of using webhook, see Onboard ServiceNow Incidents on CFTR.

To view the maximum allowed limit of webhooks that you can create based on your license, go to Admin Panel > License Management.

Before you Start

Ensure that you have permission to View Webhook and Create/Update Webhook to access the Webhooks feature.

Note

Access permissions can be assigned only to a User Group. Contact your Administrator to avail this permission.

Steps

  1. Generate a Webhook URL

  2. Configure a Trigger for the Webhook

  3. Trigger Event from Webhook Data

Generate a Webhook URL

To generate a webhook URL, do the following:

  1. Go to Admin Panel > Webhooks.

  2. Click Add Webhook.

  3. Enter the following details:

    • Title: Enter a unique title for the webhook. For example, Alert Onboarding.

    • Description: Enter a description for the webhook.

    • Expiration Date: Enter an expiry date for the webhook.

    • Workspace: If workspaces are enabled, then you must select a workspace to assign the Open API. For more information on enabling workspaces, see Enable Workspaces in Orchestrate.

    • Bot User: Select a user that can use the webhook.

    • Status: Set the webhook status as active or inactive using the toggle button. If the bot user needs to use the webhook, then the webhook must be in an active status.

    • Source Whitelisting (optional): Enable source whitelisting to allow specific IP addresses to use the webhook. This enhances the security of a webhook URL.

  4. After entering the required details, click Generate Webhook URL. A webhook URL is generated, click Copy to copy the webhook URL. The webhook URL looks like this - https://<domain>/soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356.

Configure a Trigger for the Webhook

To configure a trigger for the webhook, do the following:

  1. Go to Main Menu > Configure Triggers.

  2. Click Add Configure Trigger.

  3. Enter the source app name. For example, virustotal.

  4. Enter the event type. For example, incidentresponse.

  5. Select labels to trigger playbooks with matching labels. For example, Incident Onboarding label allows you to trigger playbooks that are associated with the same label using the trigger.

  6. Set the trigger status to active, and click Create to create the configured trigger. The associated playbook will run on the occurrence of the event defined in the configured trigger.

Trigger Event from Webhook Data

You can use the generated webhook URL to create trigger events in Orchestrate. For example, the following cURL request triggers an event using a webhook URL:

curl -X
POST '<Webhook_URL>' 
--header 'Content-Type: application/json'
--data '{
            "title": "Sample Event", 
            "app_identifier": "virustotal", 
            "action_identifier": "incidentresponse", 
            "data": {}
        }'

  • Webhook_URL: Endpoint URL of the webhook source. Example, https://<domain>/soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356

    If the source application does not support configuring custom headers for sending the source app and source event type data, then you can send them as part of the webhook URL. An example is shown below.

    https://<domain>/soarapi/webhooks_auth/events/<Event Source App>/<Event Source Type>/?token=<token>

  • header: Denotes the content type of the webhook. This is a mandatory parameter.

  • data: Contents of the POST call.

Impact of Workspaces on Webhooks

On enabling workspaces, the existing webhooks are assigned to your first workspace.

While creating a new webhook, you must select a workspace. The generated webhook URL can be used to trigger events present in the selected workspace. For more information on workspaces, see Workspaces.

Note

Once configured, you cannot change the workspace assigned to a webhook.

Manage Webhooks

You can perform the following activities to manage webhooks:

  • Edit webhooks to update webhook details such as title, expiration date, status, and more except the assigned bot user.

  • Click Filters to filter the webhooks based on Created Range, Expiry Range, and Status.

  • Click Customize Table and customize the columns of the webhooks listing table.

  • Search webhooks by title using the search bar.