Getting started

Webhooks enable real-time communication between applications. When specific events happen, one app automatically sends data to another. This integration streamlines workflows, syncs systems without constant polling, and integrates third-party services.

LiveSession triggers webhooks via preset events, with ongoing expansion. When a configured event occurs, our systems promptly notify your servers, delivering detailed event data.

Configuration

You can customize your setup within LiveSession's Settings menu. In the API > Webhooks section, oversee the URLs that facilitate LiveSessOion's interaction with your servers.

Note that you must have an Admin or Owner role to manage webhook settings.

Endpoints have the following attributes:

• URL: Each endpoint is uniquely identified by its URL, utilizing either the HTTP or HTTPS scheme. This URL signifies the server address that LiveSession establishes communication with.

• Website: The 'Website' field refers to an identifier for your chosen LiveSession-enabled website.

Once you've configured your endpoints, you can begin assigning them to specific events using Alerts.

Delivery

When an event ready for webhook transmission occurs within LiveSession, an event payload is crafted. If you've set up endpoints for that specific event type, the payload gets lined up for delivery.

These "trigger-ready" events encompass actions ideal for webhook interaction. For instance, when a session event is created, it's trigger-ready.

Event delivery typically takes mere seconds, though a strict FIFO order isn't assured. Given potential event volume, the webhook platform prioritizes throughput over rigid sequencing.

Once an event is dispatched, a payload signature is computed and included in the request. The request sent to your chosen endpoint bears these details:

• HTTP method is POST

• Content-Type of the request body is application/json

• There will be a request header named LiveSession-Signature; this includes the request signature which the recipient should verify.

• Every request body will contain a JSON object with the following fields:

  • message id - the message identifier
  • webhook_id - the webhook identifier
  • webhook_type - the webhook type
  • api_version - the webhook API version
  • account id - the account identifier
  • website id - the website identifier
  • created_at - the message creation timestamp
  • payload - the event payload

Below is a representation of the entire HTTP request:

POST /webhooks HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
LiveSession-Signature: /NLAt29+UdUod1lyzeWcbNigjzGfvtusP44dNKt4Q3U=
User-Agent: LiveSessionWebhooks/1.0
{
  "message_id": "d5932de4-a8da-4546-4439-3c640ba8dc05",
  "webhook_id": "542de45",
  "webhook_type": "session.event",
  "api_version": "v1.0",
  "account_id": "3ca3b1b",
  "website_id": "8d53ea3",
  "created_at": 1691161881,
  "payload": {
    "visitor": {
      "id": "e4d5932d-4439-4546-a8da-a8d40bc053c6",
      "name": "John Doe",
      "email": "john.doe@livesession.io",
      "params": [
        {
          "name": "plan",
          "value": "pro"
        }
      ],
      "geolocation": {
        "country_code": "PL",
        "city": "Wroclaw",
        "region": "Dolnoslaskie"
      }
    },
    "event_name": "Error",
    "time": 1691161881,
    "count": 1,
    "value": "ProductCatalog: product is not valid"
  }
}

Throttling

To prevent your servers from being overwhelmed or unintentionally participating in a service disruption on your webhook endpoint, LiveSession limits the number of events sent for a given webhook to a maximum of 1000 per minute.

If you've configured an endpoint for a high-volume event flow, like a frequently triggered custom event during user sessions, expect possible webhook delays. When the number of events for an endpoint exceeds 1000 per minute, the extra events will be queued. If the events happen really fast for a little while and then slow down, all the events might still arrive, but it could take longer than when they first happened. But if the fast rate continues for a long time, some events might not be delivered. If an event is undeliverable for 24 hours, it's treated as failed, and no more tries will be made.

The limit of 1000 events per minute is per account.

Retry behavior

LiveSession attempts to deliver a given event to your webhook endpoint for up to 8 hours with an exponential back off in beetwen 1-10 minutes interval gap from the previous attempt.

Verify the webhook

Before you proceed with responding to a webhook, it's crucial to ensure that the webhook originated from LiveSession. This verification can be accomplished by calculating a digital signature.

Every webhook request incorporates a base64-encoded HMAC-SHA256 signature included in LiveSession-Signature header. This header is created using the app's client secret in conjunction with the data transmitted in the request.

To compute the HMAC digest, follow this algorithm written in Python:

import hmac
import hashlib
import base64
# Your webhook secret key (convert to bytes if not already)
secret_key = b'your_secret_key_here'
# Received data from the webhook payload (convert to bytes if not already)
received_data = b'received_data_here'
# Received base64-encoded HMAC signature from the webhook headers
received_signature_base64 = "received_signature_here"  # Replace with actual received signature
# Function to compute HMAC-SHA256 signature and return base64-encoded result
def compute_hmac_sha256_base64(data, secret_key):
    hashed = hmac.new(secret_key, data, hashlib.sha256)
    return base64.b64encode(hashed.digest()).decode('utf-8')
# Calculate the base64-encoded HMAC-SHA256 signature for the received data
calculated_signature_base64 = compute_hmac_sha256_base64(received_data, secret_key)
# Compare the received signature with the calculated signature
if received_signature_base64 == calculated_signature_base64:
    print("Webhook signature is valid. Request is authentic.")
else:
    print("Webhook signature is invalid. Request might be tampered.")