> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Reciba una devolución de llamada HTTP en el momento en que un proyecto alcance un hito, en lugar de realizar sondeos

# Webhooks

Los webhooks permiten que VoiceCheap notifique a su servidor tan pronto como ocurra algo, para que pueda dejar de realizar sondeos
`GET /v1/translate/{projectId}/status`.

> [!NOTE]
>
> Se intenta cada entrega una sola vez. No hay reintentos; siga consultando el estado como respaldo para los eventos importantes.

## Configuración

1. Abra la [página de API](https://app.voicecheap.ai/page-api) en su cuenta de VoiceCheap.
2. En **Webhooks**, seleccione **Generar clave de firma**. La clave que empieza por `whsec_` solo aparece una vez; cópiela y guárdela en su servidor.
3. Introduzca una URL `https` en **URL de destino** y seleccione **Guardar**.

Eso es todo. Cada proyecto que inicie a partir de entonces enviará eventos a ese punto final.

> [!NOTE]
>
> Las URL de webhook deben usar HTTPS en el puerto 443 y resolver a una dirección de red pública. Se rechazan las URL con credenciales o fragmentos,
> las direcciones privadas o reservadas y las redirecciones. Esto se aplica al endpoint de la cuenta y a las URL específicas de cada proyecto.

Usa `webhooks_get`, `webhooks_update` y `webhooks_delete` mediante la API de acciones o MCP. Usa `webhooks_create_secret` solo mediante la API de acciones REST. Guarda de forma segura el secreto de firma cuando se devuelva; MCP no permite ejecutar ni consultar esta acción.

### Anulación del punto final por solicitud

`POST /v1/translate` y `POST /v1/projects` aceptan un campo opcional `webhookUrl` que anula el
punto final de la cuenta solo para ese proyecto. Es útil para enviar tráfico de prueba a otro lugar:

También puede establecer `webhookUrl` en `POST /v1/projects/{projectId}/dub` para actualizar el destino de un proyecto existente.

```bash theme={null}
curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: vc_your-key" \
  -F "file=@interview.mp4" \
  -F "targetLanguage=german" \
  -F "webhookUrl=https://staging.your-server.com/voicecheap/webhooks"
```

El secreto de firma es siempre el secreto de la cuenta; solo cambia el destino.

## Eventos

| Evento | Se dispara cuando |
| - | - |
| `project.created` | El proyecto existe y su transcripción está almacenada. Esta es su señal para descargar el SRT. |
| `project.creation.failed` | El proyecto no pudo ser creado. |
| `project.translation.completed` | La traducción finalizó y los resultados están listos. |
| `project.translation.failed` | La traducción falló. |
| `project.lipsync.completed` | Sincronización labial finalizada. |
| `project.lipsync.failed` | La sincronización labial falló. |

> [!NOTE]
>
> No hay un evento de transcripción independiente. La creación del proyecto responde antes de que termine la transcripción. `project.created` se envía
> solo después de guardar la transcripción; entonces puede obtenerla con [`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/es/api-reference/project-transcript).

## Carga útil

Cada entrega es un `POST` con un cuerpo JSON:

```json theme={null}
{
  "type": "project.created",
  "eventId": "evt_9f2c4b1d8e7a4c3f9b2d1e0a5c6b7d8e",
  "projectId": "7fa7d3a3-4f2b-4c1e-9a6d-2b3c4d5e6f70",
  "workflow": "transcription",
  "status": "success",
  "targetLanguage": "german",
  "error": null,
  "occurredAt": "2026-08-19T09:12:00.000Z"
}
```

| Campo | Tipo | Descripción |
| - | - | - |
| `type` | string | Uno de los eventos anteriores. |
| `eventId` | string | Único por evento. Úselo para eliminar duplicados. |
| `projectId` | string | El proyecto al que pertenece este evento. |
| `workflow` | string | `transcription` o `translation`. |
| `status` | string | `success` o `failed`. |
| `targetLanguage` | string | Presente solo en eventos específicos del idioma. |
| `error` | object \| null | En eventos `*.failed`, la misma forma `{ code, message }` que la API REST. Consulte [Códigos de error](https://api-docs.voicecheap.ai/docs/es/api-reference/errors.md). |
| `occurredAt` | string | Marca de tiempo ISO 8601. |

La carga útil es intencionalmente ligera. Llame a la API REST para obtener el contenido en sí.

## Verificación de la firma

Cada entrega incluye estos encabezados:

| Encabezado | Descripción |
| - | - |
| `X-VoiceCheap-Signature` | `sha256=<hex>` — HMAC-SHA256 de la carga útil, codificado con su secreto de firma. |
| `X-VoiceCheap-Timestamp` | Segundos Unix, incluidos en la cadena firmada para que pueda rechazar repeticiones. |
| `X-VoiceCheap-Event-Id` | El mismo valor que `eventId` en el cuerpo, útil en solicitudes de soporte. |

La firma cubre `<timestamp>.<raw body>`, por lo que es diferente en cada entrega y demuestra tanto
que la solicitud provino de VoiceCheap como que el cuerpo no fue modificado durante el tránsito.

```js theme={null}
import crypto from 'crypto';
import express from 'express';

const app = express();

// The raw body is required: parsing and re-serializing changes the bytes and the signature will
// never match. This is the single most common cause of failed verification.
app.post('/voicecheap/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.header('X-VoiceCheap-Timestamp');
  const signature = req.header('X-VoiceCheap-Signature')?.replace('sha256=', '') ?? '';

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const expected = crypto.createHmac('sha256', process.env.VOICECHEAP_WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');

  const isValid = expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(rawBody);
  // Acknowledge quickly, then process asynchronously.
  res.status(200).send('ok');
  handleEvent(event);
});
```

> [!WARNING]
>
> Verifique la firma antes de confiar en una entrega. Su punto de conexión es una URL pública, y la firma es lo que distingue un evento real de
> VoiceCheap de cualquier otra cosa que llegue a él.

## Respuesta

Responda con cualquier estado `2xx` para confirmar la recepción. Responda en un plazo de **10 segundos**: confirme primero y realice
el trabajo después, en lugar de procesar antes de responder.

Una respuesta que no sea 2xx o un tiempo de espera se registra como una entrega fallida y, por ahora, no se vuelve a intentar.

## Rotación del secreto

Seleccione **Rotar** en la página de la API para generar un nuevo secreto. El anterior deja de funcionar
inmediatamente, así que implemente el nuevo secreto en su servidor tan pronto como lo rote.

Eliminar el webhook elimina tanto el punto de conexión como el secreto, y las entregas se detienen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.