Webhooks

Overview

Webhooks allow MeasureLLM to send real-time notifications to your server when events occur. Instead of polling the API, your server receives instant updates when visibility changes, alerts trigger, or other events happen.

Creating a Webhook

Via Dashboard

1. Go to Settings → Webhooks
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select events to receive
5. Click "Create Webhook"

Via API

curl -X POST "https://api.measurellm.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/measurellm",
    "events": ["visibility.changed", "mention.new", "alert.triggered"],
    "secret": "your-webhook-secret"
  }'

Event Types

Payload Format

All webhook payloads follow a consistent structure:

{
  "id": "evt_abc123",
  "type": "visibility.changed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

visibility.changed

{
  "id": "evt_abc123",
  "type": "visibility.changed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "keyword_id": "kw_123",
    "keyword": "best crm software",
    "previous_score": 65,
    "new_score": 78,
    "change": "+13",
    "change_percent": "+20%",
    "platform": "chatgpt"
  }
}

mention.new

{
  "id": "evt_def456",
  "type": "mention.new",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "keyword_id": "kw_123",
    "keyword": "best crm software",
    "platform": "perplexity",
    "position": 1,
    "sentiment": "positive",
    "context": "For CRM software, I recommend [YourBrand]..."
  }
}

alert.triggered

{
  "id": "evt_ghi789",
  "type": "alert.triggered",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "alert_id": "alert_456",
    "alert_name": "Visibility Drop Alert",
    "trigger_reason": "Visibility dropped below 60",
    "keyword_id": "kw_123",
    "keyword": "best crm software",
    "current_score": 55,
    "threshold": 60
  }
}

Verifying Webhooks

Every webhook includes a signature header to verify authenticity:

Signature Header

X-MeasureLLM-Signature: sha256=abc123...

Verification Code (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const sig = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhooks/measurellm', (req, res) => {
  const signature = req.headers['x-measurellm-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Verification Code (Python)

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    sig = signature.replace('sha256=', '')
    return hmac.compare_digest(sig, expected)

Response Requirements

Your webhook endpoint must:

• Return a 2xx status code within 30 seconds
• Accept POST requests with JSON body
• Be accessible via HTTPS (required)

Retry Policy

If delivery fails, MeasureLLM retries with exponential backoff:

After 5 failed attempts, the webhook is disabled and you'll receive an email notification.

Testing Webhooks

Test Endpoint

Send a test event from the dashboard:

1. Go to Settings → Webhooks
2. Find your webhook
3. Click "Send Test"
4. Select event type
5. View delivery result

Webhook Logs

View delivery history for each webhook:

• Timestamp of each delivery
• Event type and payload
• Response status code
• Retry attempts

Best Practices

1. Respond quickly: Return 200 immediately, process async
2. Verify signatures: Always validate webhook authenticity
3. Handle duplicates: Use event IDs for idempotency
4. Log everything: Keep records for debugging
5. Monitor failures: Set up alerts for webhook failures

Tip: Use a service like webhook.site for testing during development before connecting to your production endpoint.