Vigthoria Webhooks Documentation

📖 What are Webhooks?

Webhooks are HTTP callbacks that notify your server when specific events occur. Instead of polling our API, webhooks push data to you in real-time.

Real-time Updates
Get notified instantly when generations complete, payments succeed, or subscriptions change.
Server-to-Server
Webhooks are sent directly to your server, ideal for backend automation.
Automatic Retries
Failed webhooks are automatically retried up to 5 times with exponential backoff.

🚀 Quick Setup

1

Create a Webhook Endpoint

Set up an endpoint on your server to receive webhook events:

// Express.js example
app.post('/webhooks/vigthoria', (req, res) => {
    const event = req.body;
    
    switch(event.type) {
        case 'generation.completed':
            // Handle completed generation
            break;
        case 'payment.succeeded':
            // Handle successful payment
            break;
    }
    
    res.status(200).send('OK');
});

2

Register Your Webhook

Go to vigtherius.io/settings/webhooks and add your endpoint URL.

3

Verify Signatures

Validate webhook signatures to ensure authenticity:

const crypto = require('crypto');

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

📋 Event Types

🎨 Generation Events

generation.started A generation job has started

{
  "type": "generation.started",
  "data": {
    "job_id": "job_abc123",
    "service": "music",
    "created_at": "2026-01-03T12:00:00Z"
  }
}

generation.completed A generation job has completed successfully

{
  "type": "generation.completed",
  "data": {
    "job_id": "job_abc123",
    "service": "music",
    "output_url": "https://cdn.vigthoria.io/...",
    "duration_ms": 45000
  }
}

generation.failed A generation job has failed

💳 Payment Events

payment.succeeded A payment was successfully processed

{
  "type": "payment.succeeded",
  "data": {
    "payment_id": "pay_xyz789",
    "amount": 2900,
    "currency": "usd",
    "customer_email": "user@example.com"
  }
}

payment.failed A payment attempt failed

subscription.created A new subscription was created

subscription.updated A subscription was modified

subscription.cancelled A subscription was cancelled

👤 Account Events

user.created A new user signed up

credits.depleted User's credits have run out

🔐 Security

⚠️ Always Verify Signatures

Every webhook includes a X-Vigthoria-Signature header. Always verify this signature before processing the event to prevent spoofed requests.

🔑 Webhook Secret

Your webhook signing secret is available in your dashboard at vigtherius.io/settings/webhooks. Keep this secret secure and never expose it in client-side code.

🔄 Retry Policy

If your endpoint returns a non-2xx status code, we'll retry the webhook:

1st retry: 1 minute after failure
2nd retry: 5 minutes after
3rd retry: 30 minutes after
4th retry: 2 hours after
5th retry: 24 hours after

After 5 failed attempts, the webhook is marked as failed and you'll receive an email notification.

🧪 Testing

Use the webhook testing tool in your dashboard to send test events to your endpoint. You can also use services like webhook.site or ngrok for local development.

# Test with curl
curl -X POST https://your-server.com/webhooks/vigthoria \
  -H "Content-Type: application/json" \
  -H "X-Vigthoria-Signature: sha256=..." \
  -d '{"type": "generation.completed", "data": {...}}'

🔔 Webhooks