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 for 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

Generate a Webhook URL

To generate a webhook URL, follow these steps:

Go to Admin Panel > Webhooks.
Click Add Webhook.
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.
  Note
  You will receive email notifications before and after the webhook expires.
- Bot User: Select a user who can use the webhook.
- Workspace: Select a workspace to generate a 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 and enter IP addresses or networks to use the webhook. This enhances the security of a webhook URL.
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, follow these steps:

Go to Main Menu > Configure Triggers.
Click Add Configure Trigger.
Source App: Enter the source app name. For example, virustotal.
Event Type: Enter the event type. For example, incidentresponse.
Labels: 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.
Status: Set the trigger status to active, and then 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.
- title: Title of the configured trigger.
- app_identifier: Name of the Source App from which the event is triggered. This is the same source app name you have created in step 3 of Configure a Trigger for the Webhook.
- action_identifier: Name of the event type. This is the same event type you have created in step 4 of Configure a Trigger for the 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. Hover over the webhook you want to edit, and click the More icon. Select Edit and update the details as required.
Click Filters to filter the webhooks based on Created Range, Expiry Range, and Status.
Click the Customize Table icon and you can customize the columns of the webhooks listing table by selecting the fields.
Search webhooks by title using the search bar.

Orchestrate Next Gen