Home Docs Webhooks

Webhooks

Receive real-time notifications when events happen in your Vedika integration.

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.

HMAC

SHA-256 Signed Payloads

3

Automatic Retries

10

Event Types

Event Types

chart.*Birth Chart Events

chart.createdA new birth chart was generated
chart.updatedBirth chart was recalculated

ai.*AI Events

ai.response.completedAI finished generating a response
ai.batch.completedBatch AI processing completed

billing.*Billing Events

billing.subscription.createdNew subscription activated
billing.subscription.updatedPlan changed or renewed
billing.subscription.cancelledSubscription was cancelled
billing.payment.failedPayment attempt failed

usage.*Usage Alerts

usage.threshold.reached80% of monthly quota used
usage.limit.exceededMonthly quota exhausted

Setup Webhooks

1. Configure in Dashboard

Go to Console → Webhooks → Add Endpoint

2. Or Use the API

Planned: /v2/webhooks for creating webhook endpoints from code. Available today: subscribe a chart to transit alerts delivered by email or Telegram.

// Subscribe a birth chart to transit alerts (available today)
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({
        birthDetails: {
            datetime: '1990-05-15T10:30:00',
            latitude: 19.07,
            longitude: 72.87,
            timezone: '+05:30'
        },
        email: '[email protected]',
        alertTypes: ['saturn_return', 'sade_sati_peak', 'eclipse_on_natal'],
        notifyChannels: ['email']
    })
});

const subscription = await response.json();
console.log('Subscription ID:', subscription.subscriptionId);

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:

AttemptDelayTotal Time
1st retry1 minute~1 minute
2nd retry5 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

# Simulate a delivery against your own local receiver
BODY='{"id":"evt_test_001","type":"chart.created","created":1703548800,"data":{"chart_id":"cht_test"}}'
SECRET='your_webhook_secret'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST http://localhost:3000/webhooks/vedika \
  -H "Content-Type: application/json" \
  -H "X-Vedika-Event: chart.created" \
  -H "X-Vedika-Signature: sha256=$SIG" \
  -d "$BODY"

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.