Webhooks & Public API

BuddyStat provides two integration methods: outgoing webhooks for push-based event streaming and a REST API for pull-based data access.

Outgoing Webhooks

Webhooks allow BuddyStat to send real-time event data to your own servers via HTTP POST requests.

Supported Events

Security

Each webhook payload is signed with HMAC-SHA256 using your webhook's secret key. Verify the signature on your end to ensure the payload came from BuddyStat and hasn't been tampered with.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Delivery

• 10-second timeout — Your endpoint must respond within 10 seconds
• Delivery audit log — Each delivery attempt is logged with status code, response body, and timestamp
• Retry on failure — Failed deliveries are retried automatically

Managing Webhooks

1. Go to Site Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select which events to receive
5. Save and copy your secret key for signature verification

REST API

The public REST API v1 provides programmatic access to your analytics data.

Authentication

Use Bearer token authentication with an API key. Create API keys in Account Settings → API Keys.

Endpoints

Rate Limits

• 50 requests per minute per API key
• Rate limit headers included in responses (X-RateLimit-Remaining, X-RateLimit-Reset)

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.buddystat.com/api/v1/sites/1/stats

const response = await fetch('https://app.buddystat.com/api/v1/sites/1/stats', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();

import requests

response = requests.get(
    'https://app.buddystat.com/api/v1/sites/1/stats',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()