Documentation

7.4. HTTP POST / Webhooks

The HTTP POST Event Handler is where you can integrate SFTPPlus with your web resource. To read more, please go to :doc: the Developer Documentation </developer/http-api-event-handler>.

In this section you will find the configuration option available to the http event handler.

7.4.1. name

Default value

''

Optional

No

From version

2.10.0

Values
  • Any text.

Description

Human-readable short text used to identify this event handler.

7.4.2. description

Default value

''

Optional

Yes

From version

2.10.0

Values
  • Any text.

Description

Human-readable text that describes the purpose of this event handler.

7.4.3. type

Default value

''

Optional

No

From version

2.10.0

Values
  • file-dispatcher - Dispatch a file into one or multiple paths.

  • http - HTTP POST request (unsecured).

  • local-file - Append events to a file located on the local file system.

  • email-sender - Send emails as an SMTP client.

  • windows-eventlog - Send events to Windows EventLog Service.

  • standard-stream - Send events to standard output.

  • syslog - Local Unix socket or remote IP:PORT address for Syslog.

  • create-archive - Create/Compresses one or more files.

  • extract-archive - Extract/Uncompressed a file.

  • external-executable - Execute an external script or program.

  • openpgp - Encrypt/Decrypt files using OpenPGP.

  • rabbitmq - Publish event to RabbitMQ AMQP 0-9-1 server.

  • extension - For custom event handlers implemented using our API.

Description

This option specifies the type of the event handler. Each type has a set of specific configuration options.

7.4.4. target

Default value

''

Optional

Yes

Values
  • Comma separated list of event ids.

  • Comma separated list of event ids starting with an exclamation mark.

  • Leave empty to handle all events.

From version

2.10.0

Description

Define a comma separated list of event ids to have the event handler triggered only for those events.

When you want to have it triggered for all the events, excepting a few events you should prefix each event id with the exclamation mark (!).

Leave it empty to handle all events.

Note

Combining the two methods is not supported as the same result can be achieved by allowing only the desired events, all the others will be ignored.

7.4.5. groups

Default value

''

Optional

Yes

Values
  • Comma separated list of event groups.

  • Comma separated list of event groups starting with an exclamation mark.

  • Empty.

From version

3.39.0

Description

Defines the list of event groups for which this handler is active.

When you want to handle all the events, except for the ones from a set of groups, prefix the group names with the exclamation mark (!).

An event can be a member of one or multiple groups. The event is handled if any of its groups is found in the list of configured allowed groups. The event is not handled if any of its groups is found in the list of configured ignored groups (starting with !).

Leave it empty to handle events from all groups.

7.4.6. usernames

Default value

''

Optional

Yes

Values
  • Comma separated list of usernames.

  • Comma separated list of usernames starting with an exclamation mark.

  • Leave empty to handle all events.

From version

3.9.0

Description

Comma separated list of usernames whose events are handled by this event handler. A username can include OS accounts, application accounts, and any accounts accepted by any authentication method including external HTTP accounts.

When you want to have it triggered for all the events, excepting a few events you should prefix each username with the exclamation mark (!).

Leave it empty to handle events from any users or events which are not associated with any user.

7.4.7. components

Default value

''

Optional

Yes

Values
  • Comma separated list of UUIDs.

  • Comma separated list of UUIDs starting with an exclamation mark.

  • Leave empty to handle all events.

From version

3.18.0

Description

Comma separated list of component UUIDs for which events are handled by this event handler.

When you want to have it triggered for all the events, excepting a few events you should prefix each UUID with the exclamation mark (!).

Leave it empty to handle events emitted by any component.

7.4.8. source_addresses

Default value

Empty

Optional

Yes

Values
  • Comma separated list of IP addresses.

  • List of IP addresses starting with an exclamation mark.

  • Empty.

From version

3.40.0

Description

Comma separated list of source IP addresses of the remote peers, which are handled by this event handler.

When you want to have it triggered for all the addresses, excepting a few addresses you should prefix each address with the exclamation mark (!).

Leave it empty to handle events emitted by any source address.

7.4.9. data_filter

Default value

''

Optional

Yes

Values
  • Comma separated list of data member name and filter expression.

  • Leave empty to handle all events.

From version

3.22.0

Description

Comma separated definition with name of attribute data member and the targeted matching expression.

Data member names are configured with insensitive cases.

For more details about the available expressions see the matching expression documentation.

The following example will extract the to be matched/filtered value from the path data member of the event. The extracted value is then matched against the */folderA/* globbing expression:

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
data_filter = path, */folderA/*

See the usage instructions for more operational details.

You can filter only based on a single data member with a single matching expression.

Leave it empty to not filter based on the event's attached data.

7.4.10. fail_after_errors

Default value

10

Optional

Yes

From version

3.0.0

Values
  • An integer number greater than 0.

  • 0 Disabled.

Description

Number of consecutive errors after which the event handler will automatically stop with a failed state.

Setting this to 0 will disable the feature. The event handler will no longer stop regardless of the number of errors encountered.

7.4.11. url

Default value

''

Optional

No

Values
  • URL

  • Comma separated list of URLs (Since 3.51.0)

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

You can define a fall-back/redundant URL using a comma separates list of URLs. The first URL from the list will be used. When failing to get a response for the first URL, the remaining URLs are tried. Since 3.51.0.

7.4.12. timeout

Default value

120

Optional

Yes

Values
  • Number of seconds.

From version

4.16.0

Description

Duration, in seconds, to wait for a response from the HTTP server.

If a response is not received during this period, the event handling fails.

7.4.13. retry_count

Default value

2

Optional

Yes

From version

3.48.0

Values
  • 0

  • Positive integer

Description

This is the number of times a failed request is retried.

When set to 0, requests are never retried.

The HTTP POST request is retried on connection errors or when the server returns a 5XX HTTP code.

7.4.14. retry_increase

Default value

10

Optional

Yes

From version

3.48.0

Values
  • 0

  • Positive real number

Description

Number of seconds to add to each wait period before retrying.

This is also the value of the first retry wait period.

When set to 0, there will be no waiting time, a retry is performed right away.

7.4.15. username

Default value

''

Optional

yes

From version

3.30.0

Values
  • Text.

Description

Username used to authenticate to the remote HTTP server.

Leave this value empty in order to leave out HTTP Basic authentication.

Warning

For now, only HTTP Basic authentication is supported. This will send the username and password in clear text.

7.4.16. password

Default value

''

Optional

Yes

From version

3.30.0

Values
  • Plain text password.

  • Empty.

Description

Password associated with the configured username.

7.4.17. http_content_type

Default value

json

Optional

Yes

Values
  • custom

  • json

  • legacy-webadmin

  • soap

  • xml

From version

3.0.0

Description

Format used to send the event over HTTP.

Use custom to send the event as a custom Jinja2 template formated value.

Use json to send the event as JSON formated.

Use soap to send the event as human readable XML SOAP envelope.

Use xml to send the event as machine readable application/xml.

Use legacy-webadmin to send the events to the SFTPPlus WebAdmin server.

7.4.18. ssl_domains

Default value

Empty

Optional

Yes

Values
  • Fully qualified domain name (FQDN)

  • Comma separated list of fully qualified domain names

  • Empty

From version

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let's Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

You can generate a certificate with multiple domain names (Subject Alternative Name - SAN), by defining a comma-separated list of domain names. The first name from the list is used as the common name of the certificate, while the remaining names are used for the SAN extension.

For this option to be used, you need to define a lets-encrypt resource.

7.4.19. ssl_certificate

Default value

Empty

Optional

Yes

Values
  • Absolute path on the local filesystem.

  • Certificate in PEM text format (Since 3.40.0).

  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).

  • Empty

From version

1.6.0

To version

None

Description

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It's important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

This certificate is sent to the remote peer during the SSL/TLS handshake process.

The certificate file can contain both the certificate and the private key, in which case you don't need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by leaving this configuration option empty.

7.4.20. ssl_key

Default value

Empty

Optional

Yes

Values
  • Absolute path on the local filesystem.

  • Key as PEM text format (Since 3.40.0).

  • Empty

From version

1.6.0

Description

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

7.4.21. ssl_key_password

Default value

Empty

Optional

Yes

Values
  • Password as plain text.

  • Empty

From version

1.7.19

Description

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Leave it empty to not use a password for the private key file.

7.4.22. ssl_certificate_authority

Default value

Empty

Optional

Yes

Values
  • Absolute path on the local file.

  • Content of the CA chain (Since 3.40.0).

  • ${LETS_ENCRYPT_X3_CA}

  • ${MICROSOFT_IT_CA}

  • ${GO_DADDY_G2_G1}

  • Empty

From version

1.6.0

Description

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let's Encrypt X3 certificate authority.

  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles, G2 With Cross to G1.

To configure a component to accept the remote peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

This defines the path on the local filesystem to a file containing the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty to disable checking the issuer of the peer's certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

7.4.23. ssl_certificate_revocation_list

Default value

Empty

Optional

Yes

Values
  • Comma separated list of CRL paths or HTTP URLs.

  • crl-distribution-points

  • ${MICROSOFT_IT_CRL}

  • Empty

From version

1.6.0

Description

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

  • file:///unix/absolute/test-ca.crl

  • file://c:\\windows\\absolute\\test-ca.crl

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

  • http://example.com/some.crl

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Leave it empty to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer's certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP-based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if ssl_certificate_authority is not enabled.

7.4.24. ssl_certificate_revocation_list_refresh

Default value

0

Optional

Yes

Values
  • Number of seconds

  • 0

From version

2.8.0

Description

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if ssl_certificate_authority is not enabled.

7.4.25. ssl_cipher_list

Default value

secure

Optional

Yes

Values
  • List of SSL/TLS ciphers in OpenSSL format.

  • secure

From version

1.7.4

Description

This defined the list of ciphers accepted by this component while communicating over the network.

The special keyword secure contains all the algorithms that we currently consider secure.

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

When left empty, it will default to the secure configuration.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

7.4.26. ssl_allowed_methods

Default value

secure

Optional

Yes

Values
  • secure

  • all

  • tlsv1.0

  • tlsv1.1

  • tlsv1.2

  • tlsv1.3

From version

1.7.4

Description

This defines the comma-separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Set this to secure to allow only the TLS methods that are currently considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might be changed in the future. Any other configured value is ignored.

Set this to all to allow any supported SSL or TLS method. Any other configured value is ignored.

Currently, the following methods are officially supported:

  • tlsv1 or tlsv1.0, which is TLS 1.0.

  • tlsv1.1, which is TLS 1.1.

  • tlsv1.2, which is TLS 1.2.

  • tlsv1.3, which is TLS 1.3.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

Support for tlsv1.3 was added in version 3.47.0.

Prior to version 4.17.0, this was configured as a space separated value.

7.4.27. expected_response

Default value

Empty

Optional

Yes

Values
  • Empty

  • Matching expression (globbing or regular expression)

From version

4.2.0

Description

If the result result of a web-hook is not returned by the server with the HTTP status header, but by the content of the response, you can use this configuration to define an expected expression for a valid response.

You can read more about how to use this configuration :doc: in the HTTP API Developer</developer/http-api-event-handler> documentation page.

Leave this configuration empty to accept any response.

7.4.28. headers

Default value

Empty

Optional

Yes

Values
  • Header-Name: Header-Value

  • Multiple headers on separate lines

From version

4.2.0

Description

This defines a set of extra headers which are sent with each HTTP request.

7.4.29. extra_data

Default value

Empty

Optional

Yes

Values
  • JSON string with variables.

  • EMPTY

From version

3.38.0

Description

When left empty the HTTP request is sent using the standard SFTPPlus format associated with each content type.

When this is defined, it will be configured as a template used to send the body of the HTTP request.

When defined for json content, it defines the extra JSON values to be included in the HTTP POST payload.

The JSON can be nested and contain multiple objects/dictionaries. The root JSON object can't be an array.

JSON key and values can contain variables which will be replaced based on the event's data.

For example to send the event as an Slack Incoming WebHook message:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
url = https://hooks.slack.com/services/n2unjSpQQ4L6JIOrHoO9CKXl
http_content_type = json
extra_data = {
    "text": "{id} {message}"
    "username": "{account.name}"
    }

To send the event as custom text message:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
url = https://hooks.slack.com/services/n2unjSpQQ4L6JIOrHoO9CKXl
http_content_type = custom
headers = Content-Type: text/plain
extra_data = New event with ID {id} from {account.name}. {message}

For more details and examples see the HTTP API documentation.

Below you can find all the available variables.

The following variables (case-insensitive) are provided as context data containing information about the event being triggered:

  • id

  • uuid

  • message

  • account.name

  • account.email

  • account.peer.address

  • account.peer.port

  • account.peer.protocol

  • account.peer.family

  • account.uuid

  • component.name

  • component.type

  • component.uuid

  • timestamp.cwa_14051

  • timestamp.iso_8601

  • timestamp.iso_8601_fractional

  • timestamp.iso_8601_local

  • timestamp.iso_8601_basic

  • timestamp.iso_8601_compact

  • timestamp.timestamp

  • server.name

  • server.uuid

  • data.DATA_MEMBER_NAME

  • data_json

Not available for http_content_type = legacy-webadmin.

You can define a fall-back/redundant URL using a comma separates list of URLs. The first URL from the list will be used. When failing to get a response for the first URL, the remaining URLs are tried.