SFTPPlus Documentation

7.1.3. HTTP POST Event Handlers

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:

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/http-post-uuid]
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.1.2. url

Default value:

‘’

Optional:

No

Values:
  • URL
From version:

2.10.0

Description:

Full URL for a resource used to receive the event details. For example: http://www.acme.io/http-post-hook-url

Warning

HTTPS URLs are supported, but for now SSL certificates are not validated. SSL certificate validation will be added soon.

7.1.3.1.3. http_content_type

Default value:

json

Optional:

Yes

Values:
  • json
  • legacy-webadmin
From version:

3.0.0

Description:

Format used to send the event over HTTP.

Use json to send the event as JSON formated. Use legacy-webadmin to send the events to the SFTPPlus WebAdmin server.

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.

Each event from the events array contains the following attributes:


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

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

name:service_uuid
type:string
optional:No
description:UUID of the service emitting this event.

name:account_uuid
type:string
optional:No
description:UUID of the account for which this event was emitted. Might be null when the event has no associated account.

name:data
type:JSON Object
optional:No
description:Event specific data. See Events page for more details regarding the data available for each event.

The server contains the following attributes:


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

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:Internet suite protocol used for this connection: TCP, UDP.

The creator 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",
      "created": "12344535.2341",
      "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,
          "protocol": "TCP"
          }
        },
      "creator": {
        "uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
        "type": "ssh"
        }

      },
    {
      "id": "20040",
      "created": "12345245.1245",
      "data": {
        "subject": "event specific data."
        },
      "account": {
        "uuid": "0c12a7f9-484a-45de-b622-8a5d96061328",
        "name": "mike",
        "peer": {
          "address": "12.442.23.34",
          "port": 2355,
          "protocol": "TCP"
          }
        },
      "creator": {
        "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.