🚀 @varnetix/webhook

Ultra-fast webhook management for Varnetix - Zero configuration required!

The simplest way to manage webhooks in your Varnetix projects. Just install and use - no API keys, no project IDs, no configuration needed!

✨ Features

• 🔥 Zero Configuration - Auto-detects everything
• ⚡ Lightning Fast - Optimized for speed
• 🎯 Simple API - Just 2-3 lines of code
• 🔧 Smart Defaults - Works out of the box
• 🛡️ Type Safe - Full TypeScript support
• 📱 Framework Agnostic - Works everywhere

🚀 Quick Start

npm install @varnetix/webhook

import { webhook } from '@varnetix/webhook';

// Get your webhook URL instantly
const url = await webhook.getUrl();
console.log('Webhook URL:', url);

// Send a test webhook
await webhook.test({ event: 'user.created', userId: 123 });

// Get recent webhook logs
const logs = await webhook.logs();
console.log('Recent webhooks:', logs);

That's it! No configuration required! 🎉

📖 Common Use Cases

1. Get Webhook URL for External Services

import { webhook } from '@varnetix/webhook';

// Copy this URL to GitHub, Stripe, Slack, etc.
const webhookUrl = await webhook.getUrl();

2. Debug Incoming Webhooks

// Get all recent webhook requests
const logs = await webhook.logs();

// Filter by method or source
const postRequests = await webhook.logs({ method: 'POST' });
const githubWebhooks = await webhook.logs({ source: 'GitHub' });

// Get specific webhook details
const webhook = await webhook.getLog('log_abc123');

3. Test Your Webhook Integration

// Send test data to your webhook
await webhook.test({
  event: 'payment.completed',
  amount: 29.99,
  currency: 'USD'
});

// Send custom test payload
await webhook.test({
  type: 'user.signup',
  user: { id: 456, email: '[email protected]' }
});

4. Monitor Webhook Activity

// Get statistics
const stats = await webhook.stats();
console.log(`Total requests: ${stats.totalRequests}`);
console.log(`Requests today: ${stats.requestsToday}`);

// Get detailed breakdown
console.log('Methods:', stats.methodBreakdown);
console.log('Sources:', stats.sourceBreakdown);

5. Export Webhook Data

// Export logs as CSV for analysis
const csvData = await webhook.exportCsv();

// Export filtered data
const csvData = await webhook.exportCsv({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  source: 'Stripe'
});

🏆 Premium Features

Analytics & Insights

// Get detailed analytics
const analytics = await webhook.getAnalytics('7d');
console.log('Success rate:', analytics.successRate);
console.log('Average response time:', analytics.avgResponseTime);
console.log('Hourly breakdown:', analytics.hourlyData);

// View request trends
console.log('Recent trend:', analytics.recentTrend); // 'up', 'down', or 'stable'

Security Management

// Get current security configuration
const securityConfig = await webhook.getSecurityConfig();

// Update security settings
await webhook.updateSecurityConfig({
  rateLimit: {
    enabled: true,
    requests: 100,
    window: '1m',
    burst: 20
  },
  ipWhitelist: {
    enabled: true,
    allowedIPs: ['192.168.1.100', '10.0.0.0/8'],
    blockUnknown: true
  },
  requireSignature: true,
  allowedOrigins: ['https://myapp.com']
});

Webhook Replay

// Replay failed webhooks
const results = await webhook.replayWebhooks({
  startDate: '2025-06-01',
  endDate: '2025-06-07',
  method: 'POST'
});

// Check replay results
results.forEach(result => {
  console.log(`${result.logId}: ${result.status}`);
  if (result.error) {
    console.log('Error:', result.error);
  }
});

Advanced Export Options

// Export as JSON instead of CSV
const jsonData = await webhook.exportLogs({
  method: 'POST',
  source: 'GitHub'
}, 'json');

// Export specific webhooks
const specificData = await webhook.exportLogs({
  startDate: '2025-06-01',
  endDate: '2025-06-07',
  limit: 1000
}, 'csv');

🔧 Advanced Configuration (Optional)

While zero-config works great, you can customize if needed:

import { VarnetixWebhook } from '@varnetix/webhook';

const webhook = new VarnetixWebhook({
  projectId: 'my-project',
  orgId: 'my-org',
  baseUrl: 'https://my-custom-domain.com',
  apiKey: 'my-api-key'
});

const url = await webhook.getUrl();

🎯 Environment Variables (Auto-detected)

The SDK automatically detects these environment variables:

# Project and organization
VARNETIX_PROJECT_ID=your-project-id
VARNETIX_ORG_ID=your-org-id

# API configuration
VARNETIX_API_URL=https://api.varnetix.dev
VARNETIX_API_KEY=your-api-key

# Next.js projects
NEXT_PUBLIC_PROJECT_ID=your-project-id
NEXT_PUBLIC_ORG_ID=your-org-id
NEXT_PUBLIC_APP_URL=http://localhost:3000

📁 Configuration Files (Auto-detected)

Create .varnetix.json in your project root:

{
  "projectId": "your-project-id",
  "orgId": "your-org-id"
}

Or add to your package.json:

{
  "varnetix": {
    "projectId": "your-project-id",
    "orgId": "your-org-id"
  }
}

🎭 Framework Examples

Next.js API Route

// pages/api/webhook-test.ts
import { webhook } from '@varnetix/webhook';

export default async function handler(req, res) {
  if (req.method === 'POST') {
    // Send test webhook
    await webhook.test(req.body);
    res.json({ success: true });
  } else {
    // Get webhook URL
    const url = await webhook.getUrl();
    res.json({ webhookUrl: url });
  }
}

Express.js

import express from 'express';
import { webhook } from '@varnetix/webhook';

const app = express();

app.get('/webhook-url', async (req, res) => {
  const url = await webhook.getUrl();
  res.json({ url });
});

app.post('/webhook-test', async (req, res) => {
  await webhook.test(req.body);
  res.json({ success: true });
});

app.get('/webhook-logs', async (req, res) => {
  const logs = await webhook.logs();
  res.json({ logs });
});

React Component

import { useEffect, useState } from 'react';
import { webhook } from '@varnetix/webhook';

export function WebhookDashboard() {
  const [logs, setLogs] = useState([]);
  const [url, setUrl] = useState('');

  useEffect(() => {
    async function loadData() {
      const [webhookUrl, webhookLogs] = await Promise.all([
        webhook.getUrl(),
        webhook.logs()
      ]);
      setUrl(webhookUrl);
      setLogs(webhookLogs);
    }
    loadData();
  }, []);

  const sendTest = async () => {
    await webhook.test({ test: true });
    // Reload logs
    const newLogs = await webhook.logs();
    setLogs(newLogs);
  };

  return (
    <div>
      <h1>Webhook Dashboard</h1>
      <p>URL: {url}</p>
      <button onClick={sendTest}>Send Test</button>
      <ul>
        {logs.map(log => (
          <li key={log.logId}>{log.method} - {log.source}</li>
        ))}
      </ul>
    </div>
  );
}

📚 API Reference

webhook.getUrl()

Returns the webhook URL for your project.

webhook.logs(filter?)

Get webhook logs with optional filtering:

• method?: string - Filter by HTTP method
• source?: string - Filter by webhook source
• startDate?: string - Filter from date
• endDate?: string - Filter to date
• limit?: number - Max number of logs (default: 50)
• offset?: number - Pagination offset

webhook.test(payload?)

Send a test webhook with custom payload.

webhook.stats(timeRange?)

Get webhook statistics. Time ranges: '24h', '7d', '30d', '90d'

webhook.getToken()

Get full webhook token details.

webhook.regenerateToken()

Generate a new webhook token.

webhook.deleteLogs(logIds)

Delete specific webhook logs.

webhook.exportCsv(filter?)

Export webhook logs as CSV.

Premium Methods

webhook.getAnalytics(period?)

Get detailed webhook analytics. Periods: '1h', '24h', '7d', '30d'

webhook.getSecurityConfig()

Get current webhook security configuration.

webhook.updateSecurityConfig(config)

Update webhook security settings (rate limiting, IP whitelist, etc.)

webhook.replayWebhooks(filter?)

Replay webhooks matching the filter criteria.

webhook.exportLogs(filter?, format?)

Export webhook logs in CSV or JSON format.

🛠️ Standalone Functions

For functional programming style or one-off usage:

import { 
  getWebhookUrl, 
  getWebhookLogs, 
  sendTestWebhook,
  getWebhookAnalytics,
  replayWebhooks,
  exportWebhookLogs
} from '@varnetix/webhook';

// Basic functions
const url = await getWebhookUrl();
const logs = await getWebhookLogs({ limit: 10 });
await sendTestWebhook({ event: 'test' });

// Premium functions
const analytics = await getWebhookAnalytics('7d');
const results = await replayWebhooks({ method: 'POST' });
const csvData = await exportWebhookLogs({ source: 'GitHub' }, 'csv');

🚀 Why This SDK Rocks

1. Zero Config - Works immediately, no setup
2. Smart Defaults - Sensible defaults for everything
3. Fast - Optimized for speed and developer experience
4. Simple - Just a few functions to learn
5. Powerful - Full control when you need it
6. Type Safe - Complete TypeScript support

🤝 Support

• 📧 Email: [email protected]
• 💬 Discord: Varnetix Community
• 📖 Docs: docs.varnetix.dev

📄 License

MIT License - use it however you want!

Made with ❤️ by the Varnetix team