SFTPPlus Documentation

Start Page 7. Developer Documentation 7.1.3. HTTP POST Event Handler

7.1.3. HTTP POST Event Handler

7.1.3.1. Introduction

The HTTP POST Event Handler is where you can integrate SFTPPlus with your web resource. Simply create an event handler that will send a HTTP POST request to your remote HTTP resource based on specified server event IDs.

In the Local Manager GUI, create a new Event Handler of type Send as HTTP Post request or add the url in the configuration file for the event-handlers UUID:

[event-handlers/6d32ee50-b277-49e5-b2f4-c70eeea289a7]
url = http://www.acme.io/http-post-hook-url

For an example configuration that targets the server event ID 40007 and specifying that the JSON format be used to send the event in the HTTP body, see below:

[event-handlers/6d51ed1e-35ec-41d7-8b51-53e56c716212]
enabled = True
type = http
name = Example file transfer hook for ACME
description = Send a HTTP POST hook when event is raised
target = 40007
url = http://www.acme.io/http-post-hook-url
http_content_type = json

7.1.3.1.1. Testing the server response for a HTTP Post request hook

Using the previous example, a new Event Handler of type Send as HTTP Post request is created. In addition, the resource URL will emit a custom server code 203.

When the server event ID 40007 is triggered (opening an existing folder), the server-side SFTPPlus log will specify the server return code. In this case, 203 is the specified server return code:

20174 2017-05-12 14:12:12 other-event-http-uuid Process 0.0.0.0:0 Failed to handle event 40007 by “file-transfer-hooks”. Server returned 203

Warning

Event details are transferred using unsecured HTTP connections. Use this method only over private networks.

7.1.3.2. HTTP / HTTPS POST handlers in the audit trail

When an HTTP or HTTPS handler is used, SFTPPlus will initiate a POST client request to the configured URL with a body containing one or more events, together with the identity of the server making the request.

The request body is formatted as JSON.

The server member of the response contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the server emitting this event.

Each event from the events array contains the following attributes.

The overall structure of the event object is:

id
message
timestamp:
    cwa_14051
    timestamp
account:
    name
    uuid
    peer:
        address
        port
        protocol
component:
    name
    uuid
    type
    family
    restart_required
    start_time
    stop_time
    startup_configuration
data

The members of data are specific to each event. See Events page for more details regarding the data available for each event.

Below is the description for the main members of the event object.


name:id
type:string
optional:No
description:ID of this event. See Events page for the list of all available events.

name:message
type:string
optional:No
description:A human readable description of this event.

The timestmap contains the following attributes:


name:timestamp
type:string
optional:No
description:Date and time at which this event was created, as Unix timestamp with milliseconds.

name:cwa_14051
type:string
optional:No
description:Date and time in CWA 14051 at which this event was emitted.

The account contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the account emitting this event. In case no account is associated with the event, this will be the special process account. In case the associated account is not yet authenticated this will be the special peer account.

name:name
type:string
optional:No
description:Name of the account emitting this event.

name:peer
type:JSON Object
optional:No
description:Address of the peer attached to this account. This might be a local or remote address, depending on whether the account is used for client side or server side interaction.

The peer contains the following attributes:


name:address
type:string
optional:No
description:IP address of this connection.

name:port
type:integer
optional:No
description:Port number of this connection.

name:protocol
type:string
optional:No
description:OSI Layer 4 transport layer protocol used for this connection in the form of either TCP or UDP.

The component contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the server part emitting this event.

name:type
type:string
optional:No
description:Type of the server part emitting this event.

7.1.3.2.1. Example request with two events

Below is an example for a POST request containing two events:

POST /remote/url
Content-Type: application/json

{
  "events": [
    {
      "id": "10025",
      "timestamp": {
        "timestamp":  "1510742418.2341",
        "cwa_14051": "2017-11-15 10:40:18"
        },
      "data": {
        "path": "/path/of/file/as/seen/by/client",
        "details": "Some details about failure."
        },
      "account": {
        "uuid": "0c12a7f9-484a-45de-b622-8a5d96061328",
        "name": "mike",
        "peer": {
          "address": "12.442.23.34",
          "port": 2345,
          "family": "IPv4",
          "protocol": "TCP"
          }
        },
      "component": {
        "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
        "type": "ssh"
        }

      },
    {
      "id": "20040",
      "timestamp": {
        "timestamp":  "1510742419.1245",
        "cwa_14051": "2017-11-15 10:40:19"
        },
      "data": {
        "subject": "event specific data."
        },
      "account": {
        "uuid": "0c12a7f9-484a-45de-b622-8a5d96061328",
        "name": "mike",
        "peer": {
          "address": "2006:4820:4060::8844",
          "port": 2355,
          "family": "IPv6",
          "protocol": "TCP"
          }
        },
      "component": {
        "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
        "type": "ssh"
        }
      }
    ],
"server": {
  "uuid": "cc5c804d-0a3c-4c4c-b651-eba6fc3b5902"
  }
}

Once the server has successfully received and processed the events, it should respond with HTTP code 200:

Status: 200 OK

When the remote HTTP server is busy and we have to stop sending events, the response should display HTTP code 503 together with a Retry-After header with a value expressed in seconds. The current events are discarded.:

Status: 503 Service Unavailable
Retry-After: 3600

When we cannot get a response from the remote HTTP server (such has network failures or remote resource not found), or the response code is not one of the accepted codes, SFTPPlus will consider that the request has failed.

Failed requests are not retried and the server will stop sending events after the configured number of consecutive failures.

7.1.3.3. Sending custom data in HTTP POST request

Each payload sent by the HTTP POST event handler contains the following members, as documented in previous sections:

{
  "events": [ EVENT_DATA ],
  "server": { SERVER_DATA }
}

You can configure the event handler to add custom values to the payload. The extra values are configured in JSON format and can be nested structures.

The keys and values can contain variables which are replaced with values based on the event’s data.

For example to send the event as a Slack Incoming WebHook message, you can use this configuration:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
url = https://hooks.slack.com/services/n2unjSpQQ4L6JIOrHoO9CKXl
extra_data = {
    "text": "{message}",
    "attachments": [
      {
      "pretext": "New event {id} SFTPPlus *MFT-023-QA*",
      "author_name": "{account.name}",
      "author_icon": "https://www.sftpplus.com/static/images/logo-80.png",
      "text": "{message}",
      "footer": "Sent by SFTPPlus HTTP Post Event",
      "mrkdwn_in": ["pretext"],
      "fields": [
        {"title": "IP", "value": "{account.peer.address}"},
        {"title": "Port", "value": "{account.peer.port}"},
        {"title": "Server ID", "value": 132},
        ]
      }
    ]}

Note the usage of {id} or {message} variables inside the key names or string values. In this case, they payload sent by the HTTP POST event handler contains the following members:

{
  "events": [ EVENT_DATA_AS_BEFORE ],
  "server": { SERVER_DATA_AS_BEFORE },
  "text": "Stopped authentication "AD DAP" of type ldap. Failed at start",
  "attachments": [
    {
    "pretext": "New event 20157 SFTPPlus *MFT-023-QA*",
    "author_name": "Process",
    "author_icon": "https://www.sftpplus.com/static/images/logo-80.png",
    "text": "Stopped authentication "AD DAP" of type ldap.",
    "footer": "Sent by SFTPPlus HTTP Post Event",
    "mrkdwn_in": ["pretext"],
    "fields": [
      {"title": "IP", "value": "182.12.31.21", "short": true},
      {"title": "Port", "value": "346", "short": true},
      {"title": "Server ID", "value": 132, "short: true"},
      ]
    }
}

On Slack, the message will look like

HTTP Event as received on Slack.