Webhooks

Overview

The LivePerson Webhook is a comprehensive real-time raw data extraction tool from the LivePerson platform. It offers brands complete control over their data while addressing common extraction issues and API limitations. It supports three main use cases:

• Customizing metrics, such as creating a formula for Average Response Time (ART)
• Clients can store all raw data in one centralized location by subscribing to all realtime raw events. 
• Accessing real-time data without constant API pulls

The Webhook streamlines data management, providing a single source for extracting all raw data used by LivePerson to calculate client metrics.

What is a webhook?

A webhook enables an application to send real-time data to another application whenever a specific event occurs. For instance, when a consumer sends a message to an agent on the LivePerson platform, a webhook can instantly transmit data about the consumer's request, known as a messageConsumerEvent. Clients can subscribe to this event and receive real-time updates whenever it occurs. Unlike APIs, which require brands to request data actively, webhooks automatically transmit data to the client's endpoint as events happen. This technology ensures timely and efficient data delivery, enhancing the responsiveness and effectiveness of data management.

How to subscribe to events:  

To utilize the webhooks feature, please log in to your Data Transporter account. If you do not have an account, contact your account manager to have one set up for you. The webhook service is immediately available for all Data Transporter accounts and is currently free of charge. LivePerson reserves the right to modify this policy in the future. To set up a webhook subscription in Data Transporter, follow these steps:

1. Access the Webhook: Navigate to the side navigation bar and click on "Webhook Subscription."
2. Add a New Subscription: Click the "Add Webhook Subscription" button located at the top right of the page. This will open the creation form.

1. Name Your Subscription: Enter a descriptive name for your subscription. This will help you manage and identify the subscription easily later.
2. Provide the Endpoint: Input the endpoint URL where you want the data to be sent.
3. Enable MTLS: mTLS (Mutual Transport Layer Security) extends the standard TLS (Transport Layer Security) protocol by introducing mutual authentication between the client and server, enhancing security. Brands can opt into using mTLS, although it requires some setup. For detailed information and setup instructions, visit: mTLS Overview.
4. Select Credentials: Choose the predefined credentials from the available options.
5. Choose Events: Select the events you want to subscribe to from the dropdown menu.
6. Finalize Subscription: Once you are satisfied with your settings, click "Subscribe" to activate the webhook for the selected events.

To set up the webhook, you'll first need to configure your credentials. The next section explains how to do this.

Configure your Credentials?

To configure your credentials, follow these steps:

1. Click on 'Credentials’ under the  'Settings' section  in the side navigation bar.
2. Click the 'Add Webhook Credentials' button in the top right corner. A new form will open.

Fill out the form as follows:

1. Name: Enter a name for the credentials that will be easy to identify during the webhook setup.
2. Security Schema: Choose one of the following security methods:
   1. LP Signature: This security method allows you to configure both the hashing algorithm and the encoding technique. LP Signature is designed to ensure the integrity and authenticity of the data sent. It works by creating a signature using a predefined hashing algorithm (such as HMAC SHA-256) and encoding technique (such as Base64). The signature is then sent along with the data, allowing the recipient to verify that the data has not been altered and is from a trusted source. You will also need to generate a client ID and an API key by clicking on the 'Generate Key' button.
   2. API Key: Provide the header name and the API key.

Bearer Token: Provide the token.

Consult your security team to select the best security method for your organization. Finally, click the 'Add Webhook Credentials' button to create the credentials.

What are the events that we are supporting? 

In LivePerson, we capture ~270 events in our platform. Before we expose these events to brands, we clean, standardize, and enrich them. We currently support ten events, and we expose more based on use cases we have with brands. If you need more events to support your use case, please approach your CSM, and we can expose them for you. 

Common Header

Each webhook payload will be delivered to the brand in JSON format. The payload will consist of the following fields:

1. commonHeader: An object containing common metadata.
2. accountId: String - The Conversational Cloud ID.
3. uid: String - A unique identifier of the original source Kafka event for tracing.
4. schemaVersion: String - The schema version in the format X-X-X.
   1. MODEL: Incremented for breaking schema changes that prevent interaction with historical data.
   2. REVISION: Incremented for schema changes that may prevent interaction with some historical data.
   3. ADDITION: Incremented for schema changes that are backwards-compatible with all historical data.
5. eventTimestamp: Long - The time this event was generated by the platform (epoch in ms).
6. eventType: String - Specifies the type of event as supported in the event list above. 
7. webhookSubscriptionId: The unique identifier of the webhook subscription tied to the event

data: An object representing the body of the webhook event, which varies depending on the commonHeader.eventType. 

List of Events

AgentSnapshotEvent

AgentSnapshotEvent: This event is triggered every 30 seconds, providing snapshot information about the current state of the agent. This event provide the following information: 

1. agentId: Conversational Cloud ID of the agent (String)
2. agentName: Agent name (String)
3. totalAssignedConvWeight: Sum of agent's assigned conversation weight (Double | null)
4. maxSlots: Number of agent's slots - indicates optimal capacity as defined in the Account Configuration (Long | null)
5. totalAssignedConversations: Number of agent's assigned conversations (Long | null)

TTRStatusEvent

TTRStatusEvent: This event triggers whenever the consumer or agent publishes a message that alters the Time to Respond (TTR),  this event fires initially on message publication and with any subsequent changes affecting TTR.

1. effectiveTtr:This field represents the current effective response time required by the agent, as defined in the Account Configuration. For example, if the agent has 60 seconds to respond, this field will show the time one minute ahead of when the consumer sent a message, represented as a timestamp (Long). If the agent responds, resetting the response time for the next round, the effective TTR field will be set to -1.
2. convDetails (object):
   1. convId: Global unique identifier for the conversation (String)

AgentStateChangedEvent

AgentStateChangedEvent: This event is triggered whenever a user changes their profile status on the LivePerson platform. For example, if an agent changes their status from 'away' to 'online,' this event will capture and record the change in the agent's state.

1. agentDetails:
   1. agentId: Conversational Cloud ID of the agent (String)
   2. agentName: Agent name (String)
2. stateCode: The agent state change code (e.g., "3") (String | null)
3. stateDesc: The agent state change description (e.g., "AWAY") (String | null)
4. reasonCode: The agent state change reason code (e.g., "10015") (String | null)
5. reasonDesc: The agent state change reason description (e.g., "MEETING") (String | null)

ConversationRequestEvent

ConversationRequestEvent: This event is triggered when a consumer initiates or an agent resumes a conversation on the platform, capturing the details of the conversation's start or resumption. For example, if a consumer sends a message like 'Hey, my name is Meir, can you please help me with the following case,' this event will be triggered.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String)

ConversationEndEvent

ConversationEndEvent: This event captures the details when a conversation ends. It is triggered whenever a consumer, agent, or system closes a conversation. For example, if an agent decides to close a conversation, this event will be triggered.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String)

AppActionEvent

AppActionEvent:This event captures actions performed by LivePerson users on our platform. It is triggered whenever a monitored action occurs within the application. For example, if an agent clicks on the 'My Conversations' section, indicating focus on their conversations, this event will be triggered to track that action.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String | null)
2. viewName: Name of the view where the user performed an action (e.g., ALL_CONVERSATIONS, MY_CONVERSATIONS) (String | null). For example, if a user clicks on the 'My Conversations' view in the platform, this field will be set to MY_CONVERSATIONS.
3. actionName: The name of the action performed by the user (e.g., 'FOCUS_CONV', 'UNFOCUS_CONV') (String | null). For example, if a user switches from the 'All Conversations' view to the 'My Conversations' view, two events will be fired: the first with the view name set to ALL_CONVERSATIONS and the action set to UNFOCUS_CONV, and the second with the view name set to MY_CONVERSATIONS and the action set to FOCUS_CONV.

ParticipantAgentAddEvent

ParticipantAgentAddEvent: This event is generated when a new agent is added as a participant in a conversation. For example, if a consumer sends a message and an agent joins or is added to the conversation, this event will be triggered.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String | null)
2. agentDetails:
   1. agentId: Conversational Cloud ID of the agent (String)
   2. agentName: Agent name (String)
   3. isAssigned: True or False (Boolean | null). If this field is true, the agent is assigned to the conversation and is responsible for handling it. If false, the agent is only a participant in the conversation and is not necessarily responsible for managing it.

ParticipantAgentLeaveEvent

ParticipantAgentLeaveEvent: This event is triggered and captures details whenever an agent leaves a conversation. For example, if an agent ends the conversation, this event will be triggered alongside the ConversationEndEvent. Additionally, if the agent assigns the conversation to another agent and leaves, this event will also be triggered.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String | null)
2. agentDetails:
   1. agentId: Conversational Cloud ID of the agent (String)
   2. agentName: Agent name (String)

MessageAgentEvent

MessageAgentEvent: This event is triggered and captures details about both the conversation and the agent whenever an agent sends a message. For example, if an agent sends a message to a consumer saying, 'Hey, my name is Meir. How can I help you today?', this event will be triggered and capture the following data.

1. convDetails:
   1. convId: Global unique identifier for the conversation (String | null)
2. agentDetails:
   1. agentId: Conversational Cloud ID of the agent (String)
   2. agentName: Agent name (String)
   3. isAssigned: True or False (Boolean | null)

MessageConsumerEvent

MessageConsumerEvent: This event is triggered and captures details about the conversation whenever a consumer sends a message. For example, if a consumer sends a message to a brand saying, 'Hey, my name is Meir. I cannot log in to the system, can you assist me?', this event will be triggered and capture the following data.

• convDetails:

convId: Global unique identifier for the conversation (String | null)