[[actions-webhook]]
==== Webhook Action

A watch <<actions, action>> that connects to a web server and listens on a specific port. 
The webhook action supports both HTTP and HTTPS connections. See <<webhook-action-attributes>> for 
the supported attributes. 

[[configuring-webook-actions]]
===== Configuring Webhook Actions

You configure webhook actions in a watch's `actions` array. Action-specific attributes are
specified using the `webhook` keyword.

The following snippet shows a simple webhook action definition:

[source,json]
--------------------------------------------------
"actions" : {
  "my_webhook" : { <1>
    "transform" : { ... }, <2>
    "throttle_period" : "5m", <3>
    "webhook" : {
      "method" : "POST", <4>
	    "host" : "mylisteningserver", <5>
	    "port" : 9200, <6>
      "path": ":/{{ctx.watch_id}", <7>
	    "body" : "{{ctx.watch_id}}:{{ctx.payload.hits.total}}" <8>
    }
  }
}
--------------------------------------------------

<1> The id of the action
<2> An optional <<transform, transform>> to transform the payload before executing the `webhook` action
<3> An optional <<actions-ack-throttle, throttle period>> for the action (5 minutes in this example)
<4> The HTTP method to use when connecting to the host
<5> The host to connect to
<6> The port to connect to
<7> The path (URI) to use in the HTTP request
<8> The body to send with the request

You can use basic authentication when sending a request to a secured webservice. For example:

[source,json]
--------------------------------------------------
"actions" : {
  "my_webhook" : {
    "webhook" : {
      "auth" : {
        "basic" : {
          "username" : "<username>", <1>
          "password" : "<password>" <2>
        }
      }
      "method" : "POST",
      "host" : "mylisteningserver",
      "port" : 9200,
      "path": ":/{{ctx.watch_id}",
      "body" : "{{ctx.watch_id}}:{{ctx.payload.hits.total}}"
    }
  }
}
--------------------------------------------------

<1> The username
<2> The corresponding password

NOTE: By default, both the username and the password are stored in the `.watches` index in plain text. When
Shield is installed, Watcher can be <<shield-watch-data-encryption ,configured>> to encrypt the password before
storing it.

[[webhook-query-parameters]]
===== Query Parameters

You can specify query parameters to send with the request with the `params` field. This field simply
holds an object where the keys serve as the parameter names and the values serve as the parameter values:

[source,json]
--------------------------------------------------
"actions" : {
  "my_webhook" : {
    "webhook" : {
      "method" : "POST",
      "host" : "mylisteningserver",
      "port" : 9200,
      "path": ":/alert",
      "params" : {
        "watch_id" : "{{ctx.watch_id}}" <1>
      }
    }
  }
}
--------------------------------------------------

<1> The parameter values can contain templated strings.

[[webhook-custom-request-headers]]
===== Custom Request Headers

You can specify request headers to send with the request with the `headers` field. This field simply
holds an object where the keys serve as the header names and the values serve as the header values:

[source,json]
--------------------------------------------------
"actions" : {
  "my_webhook" : {
    "webhook" : {
      "method" : "POST",
      "host" : "mylisteningserver",
      "port" : 9200,
      "path": ":/alert/{{ctx.watch_id}}",
      "headers" : {
        "Content-Type" : "application/yaml" <1>
      },
      "body" : "count: {{ctx.payload.hits.total}}"
    }
  }
}
--------------------------------------------------

<1> The header values can contain templated strings.

[[webhook-action-attributes]]
.Webhook Action Attributes
[options="header"]
|======
| Name                                          |Required   | Default     | Description
| `request.scheme`                              | no        | http        | The connection scheme. Valid values are: `http` or `https`.
| `request.host`                                | yes       | -           | The host to connect to.
| `request.port`                                | yes       | -           | The port the HTTP service is listening on.
| `request.path`                                | no        | -           | The URL path. The path can be static text or include Mustache <<templates, templates>>. URL query string parameters must be specified via the `request.params` attribute.
| `request.method`                              | no        | get         | The HTTP method. Valid values are: `head`, `get`, `post`, `put` and `delete`.
| `request.headers`                             | no        | -           | The HTTP request headers. The header values can be static text or include Mustache <<templates, templates>>.
| `request.params`                              | no        | -           | The URL query string parameters. The parameter values can be static text or include Mustache <<templates, templates>>.
| `request.auth`                                | no        | -           | Authentication related HTTP headers. Currently, only basic authentication is supported.
| `request.body`                                | no        | -           | The HTTP request body. The body can be static text or include Mustache <<templates, templates>>. When not specified, an empty body is sent.
| `request.proxy.host`                          | no        | -           | The proxy host to use when connecting to the host.
| `request.proxy.port`                          | no        | -           | The proxy port to use when connecting to the host.
| `request.connection_timeout`                  | no        | 10s         | The timeout for setting up the http connection. If the connection could not be set up within this time, the action will timeout and fail. It is
                                                                            also possible to <<configuring-default-http-timeouts, configure>> the default connection timeout for all http connection timeouts.
| `request.read_timeout`                        | no        | 10s         | The timeout for reading data from http connection. If no response was received within this time, the action will timeout and fail. It is
                                                                            also possible to <<configuring-default-http-timeouts, configure>> the default read timeout for all http connection timeouts.
|======