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. A response delay of over 10 seconds will lead to a client-side read timeout. A read timeout is considered a failure which triggers the retry mechanism.

  • 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=. 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.

Mac mac = Mac.getInstance("HmacSHA1");
mac.init(new SecretKeySpec("THE_CLIENT_SECRET".getBytes("MUTF-8"), "HmacSHA1"));
byte[] signature = Base64.getEncoder().encode(mac.doFinal(examplePayload.getBytes("UTF-8")));
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 2 1/2 minutes 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 2 1/2 minutes 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 OAuth1 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. Failed requests are handled as described in Protocol and Security. MTLS acts as a proxy between Webhooks and the endpoint.