Receiving Webhooks from LasoExperience

LasoExperience sends events to your configured webhook endpoint via HTTP POST requests. Here's how to set up your endpoint to receive and process these events:

Endpoint Requirements

• HTTPS: Your endpoint must be accessible via HTTPS.
• POST Method: Your endpoint must accept POST requests.
• 2xx Response: Respond with a 2xx HTTP status code (e.g., 200 OK) within a reasonable time (e.g., 5 seconds) to acknowledge successful receipt of the event.

Request Structure

The request body will be a JSON payload conforming to the event schemas. The following headers will be included:

• Content-Type: application/json
• x-signature: An HMAC signature for verifying the request's authenticity (see Verifying Signatures).

Example curl Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-signature: <calculated-hmac-signature>" \
  -d '{
    "event": "activity_view",
    "time": 1678886400000,
    "session_id": "abc-123",
    "client_id": "client-456",
    "properties": {
      "activity": {
        "title": "Homepage",
        "id": "gsh231hgy123j22"
      }
    }
  }' \
  "https://your-webhook-endpoint.com"

Verifying Signatures

To ensure that webhook events are coming from LasoExperience and have not been tampered with, we include an HMAC signature in the x-signature header. You should verify this signature before processing the event.

Signature Verification Steps

1. Retrieve your webhook secret from the LasoExperience dashboard.
2. Extract the x-signature header from the request.
3. Compute an HMAC using SHA-256 with your webhook secret as the key and the request body as the message.
4. Compare your computed signature with the one in the header.

Here's an example in Node.js:

const crypto = require('crypto');

function verifySignature(requestBody, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(requestBody)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.LASO_WEBHOOK_SECRET;
  
  if (!verifySignature(JSON.stringify(req.body), signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  console.log('Received valid event:', req.body);
  res.status(200).send('Event received');
});

Error Handling and Retries

If your endpoint returns a non-2xx response or times out, LasoExperience will retry the delivery with an exponential backoff strategy:

• 1st retry: 5 minutes after the initial attempt
• 2nd retry: 30 minutes after the 1st retry
• 3rd retry: 2 hours after the 2nd retry
• 4th retry: 6 hours after the 3rd retry
• 5th retry: 24 hours after the 4th retry

After the 5th retry, the event will be marked as failed and will not be retried further.

Best Practices

1. Process events asynchronously: Acknowledge receipt of the event quickly, then process it in the background.
2. Implement idempotency: Design your webhook handler to be idempotent to avoid duplicate processing if the same event is received multiple times.
3. Monitor webhook health: Set up monitoring for your webhook endpoint to ensure it's processing events correctly.
4. Secure your endpoint: Implement proper authentication and verify signatures to ensure only legitimate requests are processed.