Generic Webhook
Generic Webhook Pack.#
This Integration is part of theSupported versions
Supported Cortex XSOAR versions: 5.5.0 and later.
The Generic Webhook integration is used to create incidents on event triggers. The trigger can be any query posted to the integration.
#
Configure Generic Webhook on Cortex XSOAR- Navigate to Settings > Integrations > Servers & Services.
- Search for Generic Webhook.
- Click Add instance to create and configure a new integration instance.
Parameter | Description | Required |
---|---|---|
longRunningPort | Listen Port | True |
username | Username (see Security for more details) | False |
password | Password (see Security for more details) | False |
certificate | Certificate (Required for HTTPS, in case not using the server rerouting) | False |
key | Private Key (Required for HTTPS, in case not using the server rerouting) | False |
incidentType | Incident type | False |
store_samples | Store sample events for mapping (Because this is a push-based integration, it cannot fetch sample events in the mapping wizard). | False |
- Click Done.
- Navigate to Settings > About > Troubleshooting.
- In the Server Configuration section, verify that the value for the instance.execute.external.\<INTEGRATION-INSTANCE-NAME> key is set to true. If this key does not exist, click + Add Server Configuration and add instance.execute.external.\<INTEGRATION-INSTANCE-NAME> and set the value to true. See the following reference article for further information.
You can now trigger the webhook URL: <CORTEX-XSOAR-URL>/instance/execute/<INTEGRATION-INSTANCE-NAME>
. For example, https://my.demisto.live/instance/execute/webhook
. Please note that the string instance
does not refer to the name of your XSOAR instance, but rather is part of the URL.
If you're not invoking the integration via the server HTTPS endpoint, then you should trigger the webhook URL as follows: <CORTEX-XSOAR-URL>:<LISTEN_PORT>/
. For example, https://my.demisto.live:8000/
.
The examples below assume you invoke the integration via the server HTTPS endpoint. In case you don't, replace the URL in the examples as suggested above.
Note: The Listen Port needs to be available, which means it has to be unique for each integration instance. It cannot be used by other long-running integrations.
#
UsageThe Generic Webhook integration accepts POST HTTP queries, with the following optional fields in the request body:
Field | Type | Description |
---|---|---|
name | string | Name of the incident to be created. |
type | string | Type of the incident to be created. If not provided, the value of the integration parameter Incident type will be used. |
occurred | string | Date the incident occurred in ISO-8601 format. If not provided, the trigger time will be used. |
raw_json | object | Details of the incident to be created. For example, {"field1":"value1","field2":"value2"} |
For example, the following triggers the webhook using cURL:
curl -POST https://my.demisto.live/instance/execute/webhook -H "Authorization: token" -H "Content-Type: application/json" -d '{"name":"incident created via generic webhook","raw_json":{"some_field":"some_value"}}'
The request payload does not have to contain the fields mentioned above, and may include anything:
curl -POST https://my.demisto.live/instance/execute/webhook -H "Authorization: token" -H "Content-Type: application/json" -d '{"string_field":"string_field_value","array_field":["item1","item2"]}'
The payload could then be mapped in the Cortex XSOAR mapping wizard:
Note that the Store sample events for mapping parameter needs to be set.
The response is an array containing an object with the created incident metadata, such as the incident ID.
#
Security- We recommend using the authorization header, as described below, to validate the requests sent from your app. If you do not use this header it might result in incident creation from unexpected requests.
- To validate an incident request creation you can use the Username/Password integration parameters for one of the following:
Basic authentication
Verification token given in a request header, by setting the username to
_header:<HEADER-NAME>
and the password to be the header value.For example, if the request included in the
Authorization
header the valueBearer XXX
, then the username should be set to_header:Authorization
and the password should be set toBearer XXX
.
- If you are not using server rerouting as described above, you can configure an HTTPS server by providing a certificate and private key.