Webhooks & Notifications

Set up real-time automatic notifications about your transcriptions. Learn how to configure webhooks, implement security, and integrate with your systems.

Why Use Webhooks?

Available Events

| Event | Description | Payload | |---|---|---| | transcription.started | Transcription started processing | Upload ID, engine, timestamp | | transcription.progress | Progress updated | Upload ID, percentage, estimate | | transcription.completed | Transcription completed successfully | Upload ID, text, duration, credits | | transcription.failed | Transcription failed | Upload ID, error, error type | | transcription.retry | Retry attempt started | Upload ID, attempt, engine | | upload.completed | File upload completed | Upload ID, size, format | | credits.low | Credits below configured threshold | Current balance, threshold |

Step-by-Step Configuration

Implementation Examples

Node.js (Express)

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

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/voxscriber', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify signature
  const signature = req.headers['x-webhook-signature'];
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== hash) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'transcription.completed':
      console.log('Transcription completed:', event.data.uploadId);
      // Process result
      break;
    case 'transcription.failed':
      console.log('Transcription failed:', event.data.error);
      // Handle error
      break;
  }

  res.status(200).json({ received: true });
});

Python (Flask)

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

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

@app.route('/webhook/voxscriber', methods=['POST'])
def handle_webhook():
    # Verify signature
    signature = request.headers.get('X-Webhook-Signature')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json

    if event['type'] == 'transcription.completed':
        process_transcription(event['data'])
    elif event['type'] == 'transcription.failed':
        handle_failure(event['data'])

    return jsonify({'received': True}), 200

Security & Best Practices

Security best practices:

• Validate the HMAC-SHA256 signature of each request
• Use HTTPS on the receiving endpoint
• Implement idempotency (same event processed only once)
• Rotate the webhook secret periodically
• Log all received events for auditing

Implementation best practices:

• Respond with 200 OK quickly (within 5 seconds)
• Process events asynchronously
• Implement a processing queue for high load
• Monitor delivery failures on the dashboard

Retry Mechanism

When your endpoint does not respond successfully (2xx), VoxScriber retries delivery:

| Attempt | Interval | Description | |---|---|---| | 1 | Immediate | First attempt | | 2 | 1 minute | After initial failure | | 3 | 5 minutes | Second retry | | 4 | 30 minutes | Third retry | | 5 | 2 hours | Final attempt |

After 5 consecutive failures, the webhook is automatically disabled and you receive an email notification.

Troubleshooting

Webhook is not being received

Possible causes: Incorrect URL, firewall blocking, invalid SSL certificate.

Solutions: Verify the URL in the dashboard, allow VoxScriber's IP in your firewall, validate your SSL certificate.

Invalid signature

Possible causes: Incorrect secret, different body encoding, middleware altering the body.

Solutions: Confirm the secret in the dashboard, use the raw body for verification, disable parsing middleware before verification.

Duplicate events

Possible causes: Retry after timeout, slow server response.

Solutions: Implement idempotency using the event.id, respond with 200 OK quickly, process asynchronously.

Continue learning

• API Integration - Complete API documentation
• Workflow Automation - Automate processes with webhooks
• Batch Processing - Transcribe multiple files