> 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. # Voz a Texto asíncrona > **Note** > > **Guía práctica** · Da por hecho que has completado la [guía de inicio rápido de Voz a Texto ](/docs/es/eleven-api/guides/cookbooks/speech-to-text). ## Resumen Los webhooks te permiten recibir notificaciones automáticas cuando se completan tus tareas de transcripción de Voz a Texto, lo que elimina la necesidad de consultar continuamente la API para obtener actualizaciones de estado. Esto resulta especialmente útil para trabajos de transcripción de larga duración o cuando procesas grandes volúmenes de archivos de audio. Cuando se completa una transcripción, ElevenLabs enviará una solicitud POST a la URL de webhook que hayas especificado con los resultados de la transcripción, incluido el texto transcrito, la detección de idioma y cualquier metadato. ## Uso de webhooks > **Note** > > Esta guía da por hecho que has [configurado tu clave de API y SDK](/docs/es/eleven-api/quickstart). Completa > primero la guía de inicio rápido si aún no lo has hecho. #### Crear o editar un webhook En el panel de ElevenLabs, ve a [**Desarrolladores** > **Webhooks**](https://elevenlabs.io/app/developers/webhooks). Haz clic en **Crear webhook** o edita un webhook existente. ![Diálogo de creación de webhook con Transcription completed seleccionado](/docs/_fern-img/866f389106e74e16586a4d68cf8160f2d27568518ff4f984c2fab81cbd1674c9.webp) Configura el webhook con lo siguiente: * **Nombre**: un nombre descriptivo para tu webhook * **URL de callback**: tu ruta HTTPS de acceso público * **Método de autenticación del webhook**: `HMAC` u `OAuth`. El cliente debe implementar el mecanismo de verificación. ElevenLabs envía cabeceras que permiten verificarlo, pero no lo imponemos. * **Eventos**: selecciona **Transcription completed**. #### Hacer llamadas a la API con el parámetro de webhook activado Al hacer llamadas a la API de Voz a Texto, incluye el parámetro `webhook` con el valor `true` para activar las notificaciones de webhook para esa solicitud concreta. ```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; } } ``` ## Carga útil del webhook Cuando se completa una transcripción, tu ruta de webhook recibirá una solicitud POST con los datos de la transcripción y del 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" } ] } } } ``` Consulta la referencia de la [API de Voz a Texto](/docs/es/api-reference/speech-to-text/v-1-speech-to-text-realtime) para conocer los detalles de la estructura de la respuesta. Si la solicitud incluía una instrucción [`transcript_edit`](/docs/es/eleven-api/guides/how-to/speech-to-text/batch/transcript-editing), el objeto `transcription` también contiene un campo `edited_transcript` con el texto editado. ## Implementar tu ruta de webhook Aquí tienes un ejemplo de cómo implementar una ruta de webhook para gestionar las notificaciones entrantes: ```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'); }); ``` ## Consideraciones de seguridad ### Verificación de firma Verifica siempre las firmas de los webhooks para asegurarte de que las solicitudes proceden de ElevenLabs. ### Requisito de HTTPS Las URL de webhook deben usar HTTPS para garantizar la transmisión segura de los datos de transcripción. ### Limitación de velocidad Implementa una limitación de velocidad en tu ruta 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); ``` ### Respuestas de error Devuelve códigos de estado HTTP adecuados: * `200-299`: Éxito: el webhook se ha procesado correctamente * `400-499`: Error del cliente: no se volverá a intentar el webhook * `500-599`: Error del servidor: se volverá a intentar el webhook ## Probar webhooks ### Desarrollo local Para las pruebas locales, usa herramientas como [ngrok](https://ngrok.com/) para exponer tu servidor local: ```bash ngrok http 3000 ``` Usa la URL HTTPS proporcionada como ruta de webhook durante el desarrollo. ### Prueba de webhooks Puedes probar tu implementación de webhook haciendo una solicitud de transcripción y supervisando tu ruta: ```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óximos pasos #### [Streaming del lado del servidor](/docs/es/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming) Transcribe audio en tiempo real con la API de streaming basada en WebSocket. #### [Referencia de la API](/docs/es/api-reference/speech-to-text) Referencia y parámetros completos de la API de Voz a Texto.