Step-by-Step Integration Guide

This guide will walk you through the end-to-end process of integrating with Aurix. You will learn how to set up a webhook listener, expose it to the internet, and register it with our API to receive real-time event notifications.

Prerequisites

API Key: You should have received a Bearer token (AURIX_API_KEY) from the Aurix team.
Python Installed: This guide uses Python for the example listener, but you can use any language.

Key Concepts: API Key vs. Webhook Secret

Before we begin, it is crucial to understand the difference between the two keys you will handle:

AURIX_API_KEY (Bearer Token):
- Purpose: Authentication and Partner Identification. Used to authorize your API requests TO Aurix (e.g., registering your URL). The system automatically identifies your partner account from this key.
- Source: Provided to you by the Aurix team. Each partner receives a unique API key.
- Usage: Header Authorization: Bearer <KEY> in your API calls.
Webhook Secret (aurix_...):
- Purpose: Verification. Used to verify that events sent FROM Aurix to your listener are genuine.
- Source: Generated by Aurix API when you register your webhook URL (Step 3).
- Usage: Used to compute the HMAC-SHA256 signature to validate the x-hub-signature header.

Step 1: Create a Webhook Listener

First, you need a server to receive the webhook POST requests. Below is a simple python script using FastAPI that listens for events and verifies the security signature.

Create a file named webhook_listener.py:

import uvicorn
from fastapi import FastAPI, Request, HTTPException, Header
import logging
import hmac
import hashlib
import os

# Configuration
# The secret you receive from Aurix after registering your URL
WEBHOOK_SECRET = os.environ.get("AURIX_WEBHOOK_SECRET", "your_generated_secret_here")

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("webhook_listener")

app = FastAPI()

def verify_signature(payload: bytes, signature_header: str, secret: str) -> bool:
    """Verifies the HMAC-SHA256 signature."""
    if not signature_header:
        return False

    # Calculate expected signature
    expected_signature = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature_header)

@app.post("/webhook")
async def receive_webhook(
    request: Request, 
    x_hub_signature: str = Header(None)
):
    # 1. Read the raw body
    raw_body = await request.body()

    # 2. Verify Signature
    # It is critical to verify the request came from Aurix
    if not verify_signature(raw_body, x_hub_signature, WEBHOOK_SECRET):
        logger.warning("Received request with invalid signature.")
        raise HTTPException(status_code=401, detail="Invalid signature")

    # 3. Parse and Process
    try:
        body = await request.json()
        event_type = body.get("event_type")

        logger.info(f"Received valid event: {event_type}")
        logger.info(f"Data: {body}")

        # Add your business logic here
        if event_type == "widget.click":
            # Handle click tracking
            pass
        elif event_type == "lead.correlated":
            # Handle new lead
            pass

        return {"status": "received"}

    except Exception as e:
        logger.error(f"Error processing webhook: {e}")
        raise HTTPException(status_code=500, detail="Internal processing error")

if __name__ == "__main__":
    print("Starting Webhook Listener on http://localhost:8005/webhook")
    uvicorn.run(app, host="0.0.0.0", port=8005)

Install Dependencies

pip install fastapi uvicorn

Run the Listener

python webhook_listener.py

Step 2: Expose Your Listener

Aurix needs to reach your listener over the public internet. For development, you can use a tool like ngrok to create a secure tunnel to your localhost.

Start ngrok:
```
ngrok http 8005
```
Copy the URL: ngrok will give you a public HTTPS URL (e.g., https://a1b2-c3d4.ngrok.io).
Append the path: Your full webhook URL will be https://a1b2-c3d4.ngrok.io/webhook.

Step 3: Register Your Webhook

Now you must tell Aurix where to send the events. You will use the Configuration API to set your URL.

Endpoint: PUT https://chatbot-api.oomdigital.com/integrations/external/webhook-config

Command:

Replace <YOUR_AURIX_API_KEY> with the key provided to you, and <YOUR_WEBHOOK_URL> with your public URL from Step 2.

curl -X PUT "https://chatbot-api.oomdigital.com/integrations/external/webhook-config" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <YOUR_AURIX_API_KEY>" \
     -d '{
           "url": "<YOUR_WEBHOOK_URL>"
         }'

Save the Secret!

The API will respond with a JSON object containing a secret.

{
  "id": "...",
  "target_url": "https://a1b2-c3d4.ngrok.io/webhook",
  "secret": "aurix_8f7d9a8b...", 
  "is_active": true
}

Copy the secret value. Stop your python script, set this as an environment variable (or update the code), and restart the listener. This secret is required to pass the signature verification in Step 1.

export AURIX_WEBHOOK_SECRET="aurix_8f7d9a8b..."
python webhook_listener.py

Step 4: Receive Events

Once registered, Aurix will immediately begin sending events to your URL.

When an anonymous user clicks the WhatsApp widget, your listener will receive:

{
  "event_type": "widget.click",
  "event_id": "evt_1704200000",
  "timestamp": "2024-01-02T12:00:00Z",
  "data": {
    "correlation_id": "wa_123456",
    "click_url": "https://example.com/landing?utm_source=google",
    "parsed_params": {
      "utm_source": "google"
    },
    "ip_address": "1.2.3.4",
    "user_agent": "Mozilla/5.0..."
  }
}

Example: Lead Correlated Event

When the user sends their first message and is identified:

{
  "event_type": "lead.correlated",
  "event_id": "evt_1704200500",
  "timestamp": "2024-01-02T12:05:00Z",
  "data": {
    "correlation_id": "wa_123456",
    "conversation_id": 987,
    "phone_number": "+15551234567",
    "lead_status": "correlated",
    "channel_id": "..."
  }
}

Example: Lead Complete Event

When the AI collects all required information from the lead:

{
  "event_type": "lead.complete",
  "event_id": "evt_1704201000",
  "timestamp": "2024-01-02T12:10:00Z",
  "data": {
    "correlation_id": "wa_123456",
    "conversation_id": 987,
    "lead_status": "complete",
    "lead_data": {
      "name": "Mock User",
      "email": "mock@example.com",
      "phone": "+15550009999",
      "company": "Mock Inc",
      "intent": "Testing Webhooks"
    }
  }
}

You have now successfully integrated with Aurix!