> 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.

# Speech to Text assíncrono

> **Note**
>
> **Guia prático** · Pressupõe que você concluiu o [início rápido do Speech to Text ](/docs/pt/eleven-api/guides/cookbooks/speech-to-text).

## Visão geral

Os webhooks permitem que você receba notificações automáticas quando suas tarefas de transcrição de Speech to Text são concluídas, eliminando a necessidade de consultar continuamente a API em busca de atualizações de status. Isso é especialmente útil para trabalhos de transcrição de longa duração ou ao processar grandes volumes de arquivos de áudio.

Quando uma transcrição é concluída, a ElevenLabs envia uma solicitação POST para o URL de webhook especificado com os resultados da transcrição, incluindo o texto transcrito, a detecção de idioma e quaisquer metadados.

## Como usar webhooks

> **Note**
>
> Este guia pressupõe que você [configurou sua chave de API e o SDK](/docs/pt/eleven-api/quickstart). Conclua
> primeiro o início rápido, caso ainda não tenha feito isso.

#### Criar ou editar um webhook

No painel da ElevenLabs, acesse
[**Desenvolvedores** > **Webhooks**](https://elevenlabs.io/app/developers/webhooks).
Clique em **Criar webhook** ou edite um webhook existente.

![Caixa de diálogo Criar webhook com Transcrição concluída selecionada](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp)

Configure o webhook com:

* **Nome**: um nome descritivo para seu webhook
* **URL de callback**: seu endpoint HTTPS acessível publicamente
* **Método de autenticação do webhook**: `HMAC` ou `OAuth`. Cabe ao cliente implementar o mecanismo de verificação. A ElevenLabs envia cabeçalhos que permitem a verificação, mas não a impomos.
* **Eventos**: selecione **Transcrição concluída**.

#### Fazer chamadas à API com o parâmetro de webhook ativado

Ao fazer chamadas à API de Speech to Text, inclua o parâmetro `webhook` definido como `true` para ativar notificações por webhook nessa solicitação específica.

```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;
  }
}
```

## Payload do webhook

Quando uma transcrição é concluída, seu endpoint de webhook recebe uma solicitação POST com os dados da transcrição e do webhook:

```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"
        }
      ]
    }
  }
}
```

Consulte a referência da [API de Speech to Text](/docs/pt/api-reference/speech-to-text/v-1-speech-to-text-realtime) para saber mais sobre os detalhes da estrutura de resposta.

Se a solicitação incluiu uma instrução [`transcript_edit`](/docs/pt/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing), o objeto `transcription` também contém um campo `edited_transcript` com o texto editado.

## Como implementar seu endpoint de webhook

Veja um exemplo de como implementar um endpoint de webhook para lidar com notificações recebidas:

```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');
});
```

## Considerações de segurança

### Verificação de assinatura

Sempre verifique as assinaturas de webhook para garantir que as solicitações vieram da ElevenLabs.

### Exigência de HTTPS

Os URLs de webhook precisam usar HTTPS para garantir a transmissão segura dos dados de transcrição.

### Limitação de taxa

Implemente a limitação de taxa no seu endpoint de webhook para evitar abusos:

```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);
```

### Respostas em caso de falha

Retorne os códigos de status HTTP apropriados:

* `200-299`: sucesso — webhook processado com êxito
* `400-499`: erro do cliente — não haverá nova tentativa de webhook
* `500-599`: erro do servidor — haverá nova tentativa de webhook

## Como testar webhooks

### Desenvolvimento local

Para testes locais, use ferramentas como o [ngrok](https://ngrok.com/) para expor seu servidor local:

```bash
ngrok http 3000
```

Use o URL HTTPS fornecido como seu endpoint de webhook durante o desenvolvimento.

### Teste de webhook

Você pode testar sua implementação de webhook fazendo uma solicitação de transcrição e monitorando seu endpoint:

```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);
}
```

## Próximas etapas

#### [Streaming no servidor](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Transcreva áudio em tempo real usando a API de streaming baseada em WebSocket.

#### [Referência da API](/docs/pt/api-reference/speech-to-text)

Referência completa e parâmetros da API de Speech to Text.