> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Asynchrone Speech to Text

> **Note**
>
> **Handleiding** · Hierbij wordt ervan uitgegaan dat je de [Speech to Text- quickstart](/docs/nl/eleven-api/guides/cookbooks/speech-to-text) hebt voltooid.

## Overzicht

Met webhooks kun je automatische meldingen ontvangen wanneer je Speech to Text-transcriptietaken zijn voltooid. Hierdoor hoef je de API niet voortdurend te pollen voor statusupdates. Dit is vooral nuttig voor langlopende transcriptietaken of wanneer je grote aantallen audiobestanden verwerkt.

Wanneer een transcriptie is voltooid, stuurt ElevenLabs een POST-request naar de door jou opgegeven webhook-URL met de transcriptieresultaten, waaronder de transcripttekst, taaldetectie en eventuele metadata.

## Webhooks gebruiken

> **Note**
>
> In deze handleiding wordt ervan uitgegaan dat je [je API-sleutel en SDK hebt ingesteld](/docs/nl/eleven-api/quickstart). Voltooi
> eerst de quickstart als je dat nog niet hebt gedaan.

#### Een webhook maken of bewerken

Ga in het ElevenLabs-dashboard naar
[**Developers** > **Webhooks**](https://elevenlabs.io/app/developers/webhooks).
Klik op **Create webhook** of bewerk een bestaande webhook.

![Dialoogvenster Create webhook met Transcription completed geselecteerd](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp)

Configureer de webhook met:

* **Naam**: Een beschrijvende naam voor je webhook
* **Callback-URL**: Je openbaar toegankelijke HTTPS-endpoint
* **Webhook Auth Method**: `HMAC` of `OAuth`. De client implementeert zelf het verificatiemechanisme. ElevenLabs stuurt headers waarmee verificatie mogelijk is, maar we dwingen dit niet af.
* **Events**: Selecteer **Transcription completed**.

#### API-calls doen met de webhookparameter ingeschakeld

Voeg bij speech-to-text-API-calls de parameter `webhook` met de waarde `true` toe om webhookmeldingen voor die specifieke request in te schakelen.

```python maxLines=0
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

def transcribe_with_webhook(audio_file):
  try:
    result = elevenlabs.speech_to_text.convert(
      file=audio_file,
      model_id="scribe_v2",
      webhook=True,
    )
    print(f"Transcription started: {result.request_id}")
    return result
  except Exception as e:
    print(f"Error starting transcription: {e}")
    raise e
```

```typescript maxLines=0
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function transcribeWithWebhook(audioFile) {
  try {
    const result = await elevenlabs.speechToText.convert({
      file: audioFile,
      modelId: 'scribe_v2',
      webhook: true,
    });

    console.log('Transcription started:', result.requestId);
    return result;
  } catch (error) {
    console.error('Error starting transcription:', error);
    throw error;
  }
}
```

## Webhook-payload

Wanneer een transcriptie is voltooid, ontvangt je webhook-endpoint een POST-request met de transcriptie- en webhookdata:

```json
{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    transcription: {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}
```

Raadpleeg de referentie voor de [Speech-to-text-API](/docs/nl/api-reference/speech-to-text/v-1-speech-to-text-realtime) voor meer informatie over de structuur van de response.

Als de request een instructie voor [`transcript_edit`](/docs/nl/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing) bevatte, bevat het object `transcription` ook een veld `edited_transcript` met de bewerkte tekst.

## Je webhook-endpoint implementeren

Hier is een voorbeeld van hoe je een webhook-endpoint implementeert om inkomende meldingen te verwerken:

```javascript
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express from 'express';

const elevenlabs = new ElevenLabsClient();

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;

    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;

      console.log(`Transcription ${requestId} completed`);
      console.log(`Language: ${language_code}`);
      console.log(`Text: ${text}`);

      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

async function processTranscription(requestId, text, language) {
  console.log('Processing completed transcription...');
}

async function handleTranscriptionError(requestId) {
  console.log('Handling transcription error...');
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});
```

## Beveiligingsoverwegingen

### Handtekeningverificatie

Verifieer altijd webhookhandtekeningen om zeker te weten dat requests van ElevenLabs afkomstig zijn.

### HTTPS-vereiste

Webhook-URL's moeten HTTPS gebruiken om transcriptiedata veilig te verzenden.

### Rate limiting

Implementeer rate limiting op je webhook-endpoint om misbruik te voorkomen:

```javascript
import rateLimit from "express-rate-limit";

const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: "Too many webhook requests from this IP",
});

app.use("/webhook", webhookLimiter);
```

### Foutresponses

Retourneer passende HTTP-statuscodes:

* `200-299`: Geslaagd - webhook is verwerkt
* `400-499`: Clientfout - webhook wordt niet opnieuw geprobeerd
* `500-599`: Serverfout - webhook wordt opnieuw geprobeerd

## Webhooks testen

### Lokale ontwikkeling

Gebruik voor lokale tests tools zoals [ngrok](https://ngrok.com/) om je lokale server toegankelijk te maken:

```bash
ngrok http 3000
```

Gebruik tijdens de ontwikkeling de meegeleverde HTTPS-URL als je webhook-endpoint.

### Webhook testen

Je kunt je webhookimplementatie testen door een transcriptierequest te doen en je endpoint te monitoren:

```javascript
async function testWebhook() {
  const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });

  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: "scribe_v2",
    webhook: true,
  });

  console.log("Test transcription started:", result.requestId);
}
```

## Volgende stappen

#### [Server-side streaming](/docs/nl/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Transcribeer audio realtime met de streaming-API op basis van WebSocket.

#### [API-referentie](/docs/nl/api-reference/speech-to-text)

Volledige Speech to Text API-referentie en parameters.