Skip to main content

Webhooks

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

List Webhooks​

GET /v1/webhooks

Retrieve all webhook configurations.

Request​
import os
from vocafuse import Client

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

webhooks = client.webhooks.list()
Response​
{
  "webhooks": [
    {
      "id": "63f8fa32-0740-4263-9bed-578156b3526b",
      "url": "https://example.com/webhook",
      "events": ["voicenote.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​
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=['voicenote.transcribed', 'voicenote.failed'],
    secret='your_webhook_secret'
)
Available Events​
  • voicenote.transcribed - Transcription finished successfully
  • voicenote.failed - Processing failed
Response​
{
  "id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "url": "https://example.com/webhook",
  "events": ["voicenote.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​
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=['voicenote.transcribed', 'voicenote.failed'],
    secret='updated-secret'
)
Response​
{
  "id": "63f8fa32-0740-4263-9bed-578156b3526b",
  "url": "https://example.com/webhook-updated",
  "events": ["voicenote.transcribed", "voicenote.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​
import os
from vocafuse import Client

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

client.webhooks('webhook_123').delete()
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:

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)

Event: voicenote.transcribed​

{
  "event": "voicenote.transcribed",
  "timestamp": "2024-01-15T10:30:45Z",
  "voicenote": {
    "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: voicenote.failed​

{
  "event": "voicenote.failed",
  "timestamp": "2024-01-15T10:30:45Z",
  "voicenote": {
    "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.