Webhooks

Configure webhook endpoints to receive real-time notifications when events occur.

---

List Webhooks

GET /v1/webhooks

Retrieve all webhook configurations.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

webhooks = client.webhooks.list()

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function listWebhooks() {
  const webhooks = await client.webhooks.list();
  console.log(webhooks.data);
}

cURL

curl -X GET "https://api.vocafuse.com/v1/webhooks" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

{
  "webhooks": [
    {
      "id": "63f8fa32-0740-4263-9bed-578156b3526b",
      "url": "https://example.com/webhook",
      "events": ["recording.transcribed"],
      "status": "active",
      "created_at": "2025-10-06T17:50:56",
      "updated_at": "2025-10-06T17:50:56",
      "uri": "/v1/webhooks/63f8fa32-0740-4263-9bed-578156b3526b"
    }
  ],
  "uri": "/v1/webhooks",
  "first_page_uri": "/v1/webhooks",
  "next_page_uri": null,
  "previous_page_uri": null,
  "page": 0,
  "page_size": 1,
  "total": 1
}

---

Create Webhook

POST /v1/webhooks

Register a new webhook endpoint for voice note events.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

webhook = client.webhooks.create(
    url='https://your-domain.com/webhooks/vocafuse',
    events=['recording.transcribed', 'recording.failed'],
    secret='your_webhook_secret'
)

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function createWebhook() {
  const webhook = await client.webhooks.create({
    url: 'https://your-domain.com/webhooks/vocafuse',
    events: ['recording.transcribed', 'recording.failed'],
    secret: 'your_webhook_secret',
  });

  console.log(`Webhook ID: ${webhook.data.id}`);
}

cURL

curl -X POST "https://api.vocafuse.com/v1/webhooks" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://yourapp.com/webhooks/vocafuse",
  "events": ["recording.transcribed", "recording.failed"],
  "secret": "your-webhook-secret"
}'

Available Events

• recording.transcribed - Transcription finished successfully
• recording.failed - Processing failed

Response

{
  "id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "url": "https://example.com/webhook",
  "events": ["recording.transcribed"],
  "secret": "test-secret",
  "status": "active",
  "created_at": "2025-10-06T17:50:56.304642Z",
  "uri": "/v1/webhooks/63f8fa32-0740-4263-9bed-578156b3526b",
  "code": "WEBHOOK_CONFIGURED"
}

---

Update Webhook

PUT /v1/webhooks/{webhook_id}

Update an existing webhook configuration.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

client.webhooks.update(
    webhook_id='webhook_123',
    url='https://example.com/webhook-updated',
    events=['recording.transcribed', 'recording.failed'],
    secret='updated-secret'
)

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function updateWebhook() {
  const webhookId = 'webhook_123';

  const updated = await client.webhooks(webhookId).update({
    url: 'https://example.com/webhook-updated',
    events: ['recording.transcribed', 'recording.failed'],
    secret: 'updated-secret',
  });

  console.log(`Updated URL: ${updated.data.url}`);
}

cURL

curl -X PUT "https://api.vocafuse.com/v1/webhooks/{webhook_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook-updated",
  "events": ["recording.transcribed", "recording.failed"],
  "secret": "updated-secret"
}'

Response

{
  "id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "url": "https://example.com/webhook-updated",
  "events": ["recording.transcribed", "recording.failed"],
  "status": "active",
  "created_at": "2025-10-06T17:50:56",
  "updated_at": "2025-10-06T18:20:00",
  "uri": "/v1/webhooks/63f8fa32-0740-4263-9bed-578156b3526b"
}

info

Event Validation: The API will return a 400 error if invalid event types are provided. Only the events listed above are supported.

---

Delete Webhook

DELETE /v1/webhooks/{webhook_id}

Remove a webhook configuration.

Request

Python

import os
from vocafuse import Client

client = Client(
    api_key='sk_live_...',
    api_secret='...'
)

client.webhooks('webhook_123').delete()

Node.js

const { Client } = require('vocafuse-node');

const client = new Client({
  apiKey: process.env.VOCAFUSE_API_KEY,
  apiSecret: process.env.VOCAFUSE_API_SECRET,
});

async function deleteWebhook() {
  await client.webhooks('webhook_123').delete();
}

cURL

curl -X DELETE "https://api.vocafuse.com/v1/webhooks/{webhook_id}" \
  -H "X-VocaFuse-API-Key: sk_live_..." \
  -H "X-VocaFuse-API-Secret: ..."

Response

Status Code: 204 No Content

---

Webhook Events

When a subscribed event occurs, VocaFuse sends a POST request to your webhook URL.

Headers

Content-Type: application/json
X-VocaFuse-Signature: sha256=...

Signature Verification

The X-VocaFuse-Signature header contains an HMAC-SHA256 signature:

Python

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return signature === `sha256=${expected}`;
}

Event: recording.transcribed

{
  "event": "recording.transcribed",
  "timestamp": "2024-01-15T10:30:45Z",
  "recording": {
    "id": "rec_abc123",
    "status": "transcribed",
    "duration": 45,
    "format": "webm",
    "identity": "user_123",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:45Z"
  }
}

Event: recording.failed

{
  "event": "recording.failed",
  "timestamp": "2024-01-15T10:30:45Z",
  "recording": {
    "id": "rec_abc123",
    "status": "failed",
    "identity": "user_123",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "error": {
    "code": "TRANSCRIPTION_FAILED",
    "message": "Audio format not supported"
  }
}

See Webhooks Documentation for complete integration guide.