Webhooks

Overview

Webhooks allow you to receive HTTP POST requests whenever specific events occur in your Vedika account. Instead of polling the API, webhooks push data to your server in real-time.

Event Types

Setup Webhooks

// Create a webhook endpoint
const response = await fetch('https://api.vedika.io/v1/webhooks', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        url: 'https://your-server.com/webhooks/vedika',
        events: ['chart.created', 'ai.response.completed', 'usage.threshold.reached'],
        secret: 'your_webhook_secret' // Optional, we'll generate one if not provided
    })
});

const webhook = await response.json();
console.log('Webhook ID:', webhook.id);
console.log('Signing Secret:', webhook.secret);

Webhook Payload

Every webhook POST request includes these headers and body:

Headers

{
  "Content-Type": "application/json",
  "X-Vedika-Signature": "sha256=abc123...",
  "X-Vedika-Event": "chart.created",
  "X-Vedika-Delivery": "evt_123456789",
  "X-Vedika-Timestamp": "1703548800"
}

Body Example (chart.created)

{
  "id": "evt_abc123xyz",
  "type": "chart.created",
  "created": 1703548800,
  "data": {
    "chart_id": "cht_789xyz",
    "user_id": "usr_456def",
    "birth_data": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    },
    "ascendant": {
      "sign": "Virgo",
      "degree": 15.42
    },
    "moon_sign": "Taurus",
    "sun_sign": "Taurus",
    "nakshatra": "Rohini"
  }
}

Signature Verification

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify Vedika webhook signature"""
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler
@app.post("/webhooks/vedika")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Vedika-Signature")

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    # Process event...
    return {"received": True}

Node.js

const crypto = require('crypto');

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

    return crypto.timingSafeEqual(
        Buffer.from(`sha256=${expected}`),
        Buffer.from(signature)
    );
}

// Express middleware
app.post('/webhooks/vedika', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['x-vedika-signature'];

    if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
        return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body);
    // Process event...
    res.json({ received: true });
});

Retry Logic

If your endpoint returns a non-2xx status code or times out (30s), we'll retry:

Testing Webhooks

# Trigger a test webhook from the CLI
curl -X POST https://api.vedika.io/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id": "wh_123", "event_type": "chart.created"}'

# Start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/vedika

Best Practices

• Always verify signatures - Never trust webhook data without verification.
• Return 2xx quickly - Acknowledge receipt, process async.
• Handle duplicates - Use the event ID for idempotency.
• Use HTTPS - We only send webhooks to HTTPS endpoints.
• Monitor failures - Set up alerts for webhook delivery failures.