Webhooks Documentation - Vedika API | Real-time Event Notifications

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.

<100ms

Average Delivery

99.9%

Delivery Rate

10

Event Types

chart.*Birth Chart Events

`chart.created`	A new birth chart was generated
`chart.updated`	Birth chart was recalculated

ai.*AI Events

`ai.response.completed`	AI finished generating a response
`ai.batch.completed`	Batch AI processing completed

billing.*Billing Events

`billing.subscription.created`	New subscription activated
`billing.subscription.updated`	Plan changed or renewed
`billing.subscription.cancelled`	Subscription was cancelled
`billing.payment.failed`	Payment attempt failed

usage.*Usage Alerts

`usage.threshold.reached`	80% of monthly quota used
`usage.limit.exceeded`	Monthly quota exhausted

Setup Webhooks

1. Configure in Dashboard

Go to Console → Webhooks → Add Endpoint

2. Or Use the API

// Create a webhook endpoint
const response = await fetch('https://api.vedika.io/api/v1/alerts/subscribe', {
    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": {
      "datetime": "1990-05-15T14:30:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "+05:30"
    },
    "ascendant": {
      "sign": "Virgo",
      "degree": 15.42
    },
    "moon_sign": "Taurus",
    "sun_sign": "Taurus",
    "nakshatra": "Rohini"
  }
}

Signature Verification

Important: Always verify webhook signatures to ensure requests are from Vedika.

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:

Attempt	Delay	Total Time
1st retry	1 minute	~1 minute
2nd retry	5 minutes	~6 minutes
3rd retry (final)	30 minutes	~36 minutes

Tip: Return a 2xx status quickly, then process events asynchronously. Use a queue (Redis, SQS) for heavy processing.

Testing Webhooks

Send Test Event

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

Local Development

Use ngrok or similar to expose your local server:

# Start ngrok
ngrok http 3000

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

View Webhook Logs

Check delivery logs in the Console → Webhooks → Logs

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.