Setting Up Webhooks | Vigthoria Tutorials

1

What Are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in Vigthoria. Instead of polling the API repeatedly, webhooks push updates to your server instantly.

Common use cases:

Song generation completed → Update your UI
GoA workflow finished → Trigger next process
Subscription changed → Update user access
API usage threshold reached → Send alerts

2

Create a Webhook Endpoint

First, create an endpoint on your server to receive webhook payloads:

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Webhook endpoint
app.post('/webhooks/vigthoria', (req, res) => {
  const signature = req.headers['x-vigthoria-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature
  const expectedSig = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSig) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle the event
  const event = req.body;
  console.log('Received event:', event.type);
  
  switch (event.type) {
    case 'generation.completed':
      handleGenerationComplete(event.data);
      break;
    case 'workflow.finished':
      handleWorkflowFinished(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  res.status(200).send('OK');
});

app.listen(3000);

Python (Flask)

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

@app.route('/webhooks/vigthoria', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Vigthoria-Signature')
    payload = request.get_data(as_text=True)
    
    # Verify signature
    expected_sig = hmac.new(
        os.environ['WEBHOOK_SECRET'].encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    if signature != expected_sig:
        return 'Invalid signature', 401
    
    event = request.json
    print(f"Received event: {event['type']}")
    
    if event['type'] == 'generation.completed':
        handle_generation_complete(event['data'])
    elif event['type'] == 'workflow.finished':
        handle_workflow_finished(event['data'])
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

3

Register Your Webhook

Go to Dashboard → API Settings
Click "Add Webhook"
Enter your endpoint URL (must be HTTPS)
Select events to subscribe to
Copy the generated Webhook Secret
Click "Save"

Security Required

Your webhook endpoint must use HTTPS. Store your webhook secret securely (environment variable). Never expose it in client-side code or commit it to version control.

4

Available Events

Subscribe to these event types:

Event Type	Description
`generation.started`	AI generation has begun processing
`generation.completed`	AI generation finished successfully
`generation.failed`	AI generation encountered an error
`workflow.started`	GoA workflow execution began
`workflow.step_completed`	Individual workflow step finished
`workflow.finished`	Entire workflow completed
`subscription.updated`	User subscription changed
`usage.threshold`	API usage reached configured threshold

5

Webhook Payload Structure

All webhooks follow this structure:

{
  "id": "evt_abc123xyz",
  "type": "generation.completed",
  "created": "2025-01-15T10:30:00Z",
  "data": {
    "generation_id": "gen_xyz789",
    "model": "vigthoria-creative-v2",
    "status": "completed",
    "result_url": "https://api.vigthoria.io/v1/results/gen_xyz789",
    "metadata": {
      "user_id": "user_123",
      "project": "my-app"
    }
  }
}

Best Practices

Respond quickly — Return 200 within 30 seconds
Process async — Queue heavy work for background processing
Handle duplicates — Use event ID for idempotency
Retry logic — Failed webhooks are retried 3 times with exponential backoff

6

Test Your Webhook

Use the dashboard to send test events:

Go to API Settings → Webhooks
Click the ⋮ menu next to your webhook
Select "Send Test Event"
Choose an event type
Verify your server receives and processes it correctly