http

= HTTP plugin
:toc: macro

The HTTP plugin provides checks for HTTP services, and HTTP-based alerts.

== Checks

=== http.get

[source,goplum]
----
check http.get "example" {
  url = "https://www.example.com/"
  content = "Example Domain"
  content_expected = true
  certificate_validity = 10d
  auth {
    username = "acidburn"
    password = "HackThePlanet"
  }
}
----

Sends an HTTP GET request to the given URL. The check passes if a response is received with
an error code less than 400.

If the `content` parameter is specified then the response body is checked for the exact string.
By default the string must be present, and the check will fail if it is not. If `content_expected`
is set to `false` then the string must NOT be present, and the check will fail if it is.

If the `certificate_validity` parameter is specified, then the connection must have
been made over TLS, and the returned certificate must be valid for at least the given duration
from now. (An expired or untrusted certificate will cause a failure regardless of this setting.)

If the `auth` settings are provided, they will be sent in a Basic authentication header. Note
that basic authentication isn't encrypted, so shouldn't be used over an insecure connection.

=== http.healthcheck

[source,goplum]
----
check http.healthcheck "example" {
  url = "https://www.example.com/health"
  check_components = true
  auth {
    username = "acidburn"
    password = "HackThePlanet"
  }
}
----

Retrieves the current status from a HTTP healthcheck endpoint. The endpoint is expected
to return JSON in a manner compatible with
https://tools.ietf.org/id/draft-inadarei-api-health-check-04.html[draft-inadarei-api-health-check-04].

If the `check_components` setting is enabled, the state of each component/dependency
reported in the healthcheck response will also be verified. This means if the overall service
status is `pass` but a component is `fail` then the Goplum check will fail.

If the `auth` settings are provided, they will be sent in a Basic authentication header. Note
that basic authentication isn't encrypted, so shouldn't be used over an insecure connection.

== Alerts

=== http.webhook

[source,goplum]
----
alert http.webhook "example" {
  url = "https://www.example.com/incoming"
}
----

Sends alerts as a POST request to the given webhook URL with a JSON payload:

[source,json]
----
{
  "text": "Check 'Testing' is now good, was failing.",
  "name": "Testing",
  "type": "debug.random",
  "config": {
    "percent_good": 0.8
  },
  "last_result": {
    "state": "failing",
    "time": "2020-09-17T17:55:02.224973486+01:00",
    "detail": "Random value 0.813640 greater than percent_good 0.800000"
  },
  "previous_state": "failing",
  "new_state": "good"
}
----