Protocol and Security

  • Webhooks notifications are sent as POST requests over TLS. Every endpoint is required to be set up with a valid server side SSL certificate supporting at least TLS version 1.2.

  • Each Webhooks notification request contains LivePerson standard headers which have the header name prefix of “x-liveperson-”.

  • Each endpoint is expected to immediately respond to a request. Connection attempts time out after 5 seconds. A response delay of over 5 seconds will lead to a read timeout. Both timeouts are a failure triggering the retry mechanism. Apps with at least one endpoint responding slower than 2.5 seconds over 2 minutes may be disabled at any time without prior warning.

  • An endpoint is expected to respond with either a 200 or 201 response code to a notification request. Any other response code will be considered as a notification request failure which triggers the retry mechanism.

Authentication

  • Each Webhook call will contain the following authentication headers:

    • x-liveperson-account-id: The unique LivePerson account identifier. Can be used to differentiate registration of different accounts, when the same url is used for multiple accounts.

    • x-liveperson-client-id: The unique client application identifier. The client_id that the consumer receives from their account manager after the App Installation process.

    • x-liveperson-signature: A token generated by signing the payload using the client-secret. A SHA1 signature of the payload and the client_secret (given by the account manager in the Application Installation process) preceded with sha1= is sent by default. For example: sha1=12DcfY3NhieG0uMlGlNX/SHWBeQ=. Webhooks also supports SHA256 for specific accounts and signature for SHA256 is preceded with sha256=. For example: sha256=xcF8VakxqTEyCxiQTwStupGCz3NC4FFTqXifBmmIRBM=. For both signature algorithms SHA1 and SHA256 it is possible to specify the encoding between Base64 and Hexadecimal. In the configuration, it is possible to set up the following signature algorithms and encodings:

      • SHA1 (default Base64 encoding)
      • SHA1_WITH_BASE64
      • SHA1_WITH_HEX
      • SHA256 (default Base64 encoding)
      • SHA256_WITH_BASE64
      • SHA256_WITH_HEX

      The signature algorithm and encoding can be configured using the signingAlgorithm field. For example, consider the following configuration that uses the SHA1 algorithm with Base64 encoding:

      {
  "client_name": "Example configuration",
  "capabilities": {
    "webhooks": {
      "signingAlgorithm": "SHA1_WITH_BASE64",
      "ms.MessagingEventNotification.ContentEvent": {
        "endpoint": "https://www.application.endpoint.com/",
         "max_retries": 3
      },
      "ms.MessagingEventNotification.RichContentEvent": {
        "endpoint": "https://www.application.endpoint.com/"
      }
    }
  }
}

      If no signing algorithm is set, the SHA1 algorithm with Base64 encoding is used as a default (SHA1). Support for signature algorithm for a specific account can be requested by contacting your technical account manager. Here is an example how to calculate this signature in Java:

// See below the example of a JSON payload. Its content is the body
// of the HTTP request that comes from Webhooks service.

String examplePayload = {
   "kind":"req",
   "id":"1",
   "type":"ms.PublishEvent",
   "body":{
      "dialogId":"123a4567-b89c-12d3-e456-789123456789",
      "event":{
         "type":"ContentEvent",
         "contentType":"text/plain",
         "message": "Example of message to be sent"
      }
   }
}

// This is an example of how the payload can be signed by using
// the client's secret and the HmacSHA1 algorithm with Base64 encoding.
// HmacSHA1 is supported by default.  HmacSHA256 algorithm is decided based on which accountid the SHA256 is supported for.

Mac mac = Mac.getInstance("HmacSHA1"); // Use HmacSHA256 for SHA256 signature
mac.init(new SecretKeySpec("THE_CLIENT_SECRET".getBytes("UTF-8"), "HmacSHA1")); // Use HmacSHA256 for SHA256 signature
byte[] signature = Base64.getEncoder().encode(mac.doFinal(examplePayload.getBytes("UTF-8"))); // Use Base64 encoding
System.out.println(signature);

Mutual Transport Layer Security (MTLS)

Apart from sending Authentication headers, Webhooks supports MTLS. For every endpoint, Webhooks will ask MTLS every 150 seconds if there is a mapping from the endpoint, account and service WEBHOOKS to a certificate. If there is a certificate, Webhooks will start to redirect all requests for this endpoint to MTLS. This means, once MTLS is configured for an endpoint, Webhooks will pick up the configuration automatically after 150 seconds at the latest. For example, assume that account 125634 has a certificate configured for url https://liveperson.com/endpoint and service WEBHOOKS. When a ContentEvent should be send to this endpoint, Webhooks will redirect it to MTLS as follows:

POST <mtlsGateway>/mtls/account/125634 HTTP/1.1
LP-service-name: WEBHOOKS
LP-forward-url: https://liveperson.com/endpoint
Authorization: OAuth <…>

{
   "kind":"req",
   "id":"1",
   "type":"ms.PublishEvent",
   "body":{
      "dialogId":"123e4567-e89b-12d3-a456-426655440000",
      "event":{
         "type":"ContentEvent",
         "contentType":"text/plain",
         "message":"Send message"
      }
   }
}

The value for mtlsGateway is taken from the Domain API. The request is sent to the forward endpoint with account 125634. LP-service-name is always set to WEBHOOKS and LP-forward-url is the endpoint url https://liveperson.com/endpoint. The Authorization header is computed using an OAuth 1.0 key and secret with rights for communicating with the MTLS service.

In the example request above, a ContentEvent is sent to MTLS. MTLS receives the request, creates a new TLS context, maps the service, endpoint and account to a certificate, retrieves the certificate from VAULT and attaches it to the TLS context. Then, it forwards the newly constructed request to the endpoint. The response of the endpoint is given back to Webhooks. MTLS acts as a proxy between Webhooks and the endpoint. mTLS detects if the request is failed at client server side then it will wrap the response in 424 with url and error message in the header. In case of 424 response, response header will be populated with LP-message-from-transport and LP-error-from-transport.