TheHive webhooks

TheHive can notify external system of modification events (case creation, alert update, task assignment, ...). To use webhooks notifications, 2 steps are required: configure a notification, and activate it.

1. Define webhook endpoints

The configuration can accept following parameters:

Parameter	Type	Description
name	string	the identifier of the endpoint. It is used when the webhook is setup for an organisation
version	integer	defines the format of the message. If version is 0, TheHive will send messages with the same format as TheHive3. Currently TheHive only supports version 0.
wsConfig	dict	the configuration of HTTP client. It contains proxy, SSL and timeout configuration.
auth	dict	the configuration of authenticationI. It contains type, and additional options.
includedTheHiveOrganisations	list of string	list of TheHive organisations which can use this endpoint (default: all ([*])
excludedTheHiveOrganisations	list of string	list of TheHive organisations which cannot use this endpoint (default: None ([]) )

The following section should be added in application.conf :

## Webhook notification
notification.webhook.endpoints = [
  {
    name: local
    url: "http://127.0.0.1:5000/"
    version: 0
    wsConfig: {}
    auth: {type: "none"}
    includedTheHiveOrganisations: ["*"]
    excludedTheHiveOrganisations: []
  }
]

Use a proxy

Wehbook call can go through a proxy, in which case, Webhooks configuration requires a wsConfig config

notification.webhook.endpoints = [
  {
    name: local
    url: "http://127.0.0.1:5000/"
    version: 0
    wsConfig {
      proxy {
        host: "10.1.2.10"
        port: 8080
      }
    }
    auth: {
      type: "none"
    }
    includedTheHiveOrganisations: ["*"]
    excludedTheHiveOrganisations: []
  }
]

Use an authentication method

Webhook endpoints can be authenticated, in this case, Webhook configuration requires a auth setting. Supported methods are:

No Auth (Default)Basic AuthBeared AuthKey Auth

  auth: { 
      type: "none" 
  }

  auth: { 
      type: "basic", 
      username: "foo", 
      password: "bar" 
  }

  auth: { 
      type: "bearer", 
      key: "foobar" 
  }

  auth: { 
      type: "key", 
      key: "foobar" 
  }

Warning

In 4.1.0 release, the auth config is REQUIRED.

Examples

Example

## Webhook notification
notification.webhook.endpoints = [
  {
    name: local
    url: "http://127.0.0.1:5000/"
    version: 0
    wsConfig {
      proxy {
        host: "10.1.2.10"
        port: 8080
      }
    }
    auth: {
      type: "bearer",
      key: "API_KEY"
    }
    includedTheHiveOrganisations: ["ORG1", "ORG2"]
    excludedTheHiveOrganisations: ["ORG3"]
  }
]

2. Activate webhooks

This action must be done by an organisation admin (with permission manageConfig) and requires to run a curl command:

read -p 'Enter the URL of TheHive: ' thehive_url
read -p 'Enter your login: ' thehive_user
read -s -p 'Enter your password: ' thehive_password

curl -XPUT -u$thehive_user:$thehive_password -H 'Content-type: application/json' $thehive_url/api/config/organisation/notification -d '
{
  "value": [
    {
      "delegate": false,
      "trigger": { "name": "AnyEvent"},
      "notifier": { "name": "webhook", "endpoint": "local" }
    }
  ]
}'

---

Last update: October 13, 2023 07:01:35